diff options
| -rw-r--r-- | doc/intro.cli | 188 |
1 files changed, 97 insertions, 91 deletions
diff --git a/doc/intro.cli b/doc/intro.cli index 6e27b72..efc8e8f 100644 --- a/doc/intro.cli +++ b/doc/intro.cli @@ -7,10 +7,7 @@ // TODO // // @@ STL christmass egg? -// @@ link to --verbose -// @@ links for commands // @@ refs to further docs -// @@ update for Mac OS in INSTALL // // STYLE // @@ -51,7 +48,7 @@ Hello, Windows! $ bpkg create -d hello cxx created new configuration in hello/ -$ cd hello +$ cd hello/ $ bpkg add https://build2.org/pkg/1/hello/stable added repository build2.org/hello/stable @@ -63,10 +60,10 @@ $ bpkg build hello build libhello 1.0.0+1 (required by hello) build hello 1.0.0 continue? [Y/n] y -libhello-1.0.0+1.tar.gz 100% of 1489 B 983 kBps 00m01s +libhello-1.0.0+1.tar.gz 100% of 1489 B 983 kBps 00m01s fetched libhello 1.0.0+1 unpacked libhello 1.0.0+1 -hello-1.0.0.tar.gz 100% of 1030 B 6882 kBps 00m01s +hello-1.0.0.tar.gz 100% of 1030 B 6882 kBps 00m01s fetched hello 1.0.0 unpacked hello 1.0.0 configured libhello 1.0.0+1 @@ -88,9 +85,10 @@ more of a technology preview rather than anything final. But if you want to start playing with it, welcome and join the \l{https://lists.build2.org mailing list}! -Our approach to developing \c{build2} is to first get the hard parts (such as -header dependency extraction combined with auto-generated source code) right -before focusing on completeness. In other words, we go depth rather than +Our approach to developing \c{build2} is to first get the hard parts right +before focusing on completeness. So while we might still be extracting header +dependencies on every run (no caching yet) they do play well with +auto-generated source code. In other words, we go depth rather than breadth-first. As a result, there are plenty of limitations and missing pieces, especially in the build system. The most notable ones are: @@ -120,10 +118,9 @@ tools, such as the \i{build robot} (\c{bbot}), are in the works. Then there is \l{https://cppget.org/ cppget.org} which we hope will become \i{the C++ package repository}. -The goal of this document is to give a basic idea of what the \c{build2} -toolchain can do for you so that you can decide if you are interested and want -to learn more. Further documentation is referenced at the end of this -introduction. +The goal of this document is to give you a basic idea of what the \c{build2} +toolchain can do so that you can decide if you are interested and want to learn +more. Further documentation is referenced at the end of this introduction. The \c{build2} toolchain is self-hosted and self-packaged (and, yes, it is on \l{https://cppget.org/ cppget.org}). It could then serve as its own example. @@ -132,23 +129,23 @@ it (that chicken and egg problem again) and this step wouldn't serve our goal of quickly learning what \c{build2} is about. So, instead, we will start with a customary \i{\"Hello, World!\"} example which you won't yet be able to try yourself (but don't worry, complete terminal output will be shown). If at the -end you find \c{build2} appealing, the next section provides detailed -bootstrapping and installation instructions (and, yes, you get to run that -coveted \c{bpkg update bpkg}). Once the \c{build2} installation is complete, -you can come back to the \i{\"Hello, World!\"} example and try all the steps -for yourself. - -This introduction explores the \i{consumer} side of the \i{\"Hello, World!\"} -example. That is, we assume that someone was kind enough to create and package -the \c{libhello} library and the \c{hello} program and we will learn how to -obtain and build them as well as keep up with their updates. And so, without -further ado, let's begin. +end you find \c{build2} appealing, the following section jumps right into +bootstrapping and installation (and, yes, you get to run that coveted \c{bpkg +update bpkg}). Once the \c{build2} installation is complete, you can come back +to the \i{\"Hello, World!\"} example and try all of the steps for yourself. + +This introduction explores the \i{consumer} side of \i{\"Hello, World!\"}. +That is, we assume that someone was kind enough to create and package the +\c{libhello} library and the \c{hello} program and we will learn how to obtain +and build them as well as keep up with their updates. And so, without further +ado, let's begin. The first step in using \c{bpkg} is to create a \i{configuration}. A configuration is a directory where packages that require similar compile settings will be built. You can create as many configurations as you want: for different C++ compilers, debug/release, 32/64-bit, or even for different days -of the week, if you are so inclined. Say we want a GCC 5 release build: +of the week, if you are so inclined. Say we are in the mood for a GCC 5 +release build today: \ $ mkdir hello-gcc5-release @@ -157,20 +154,20 @@ $ bpkg create cxx config.cxx=g++-5 config.cxx.coptions=-O3 created new configuration in /tmp/hello-gcc5-release/ \ -Let's discuss that last command line: \c{create} is the \c{bpkg} command for -creating a new configuration. As a side note, if you ever want to get help for -any \c{bpkg} command, run \c{bpkg help <command>}. To see a list of commands, -run just \c{bpkg help}. While we are at it, if you ever want to see what -\c{bpkg} is running underneath, there is the \c{-v} option. And if you really -want to get under the hood, use \c{--verbose <level>}. +Let's discuss that last command line: \l{bpkg-cfg-create(1) \c{bpkg create}} is +the command for creating a new configuration. As a side note, if you ever want +to get help for any \c{bpkg} command, run \c{bpkg help <command>}. To see a +list of commands, run just \l{bpkg-help(1) \c{bpkg help}} (or see +\l{bpkg(1)}). While we are at it, if you ever want to see what \c{bpkg} is +running underneath, there is the \c{-v} option. And if you really want to get +under the hood, use \l{bpkg-common(1) \c{--verbose <level>}}. After the command we have \c{cxx} which is the name of the \c{build2} build system module. As you might have guessed, \c{cxx} provides support for the C++ compilation. By specifying this module during the configuration creation we configure it (yes, with those \c{config.cxx...} variables that follow) for the -entire configuration. That is, every package that is built in this -configuration and that uses the \c{cxx} module inherits the settings that we -just specified. +entire configuration. That is, every package that we will build in this +configuration and that uses the \c{cxx} module will inherit these settings. The rest of the command line are the configuration variables for the \c{cxx} module with \c{coptions} standing for \i{compile options} (there are also @@ -180,7 +177,7 @@ module with \c{coptions} standing for \i{compile options} (there are also Ok, configuration in hand, where can we get some packages? \c{bpkg} packages come from \i{repositories}. A repository can be a local filesystem directory or a remote URL. Our example packages come from their own remote \i{\"Hello, -World!\"} repository: \c{https://build2.org/pkg/1/hello/stable/} (go ahead, +World!\"} repository: \c{\l{https://build2.org/pkg/1/hello/stable/}} (go ahead, browse it, I will wait). Instead of scouring repository manifests by hand (I know you couldn't resist), @@ -193,17 +190,20 @@ hello 1.0.0 libhello 1.0.0+1 \ -If we want to use a repository as a source of packages in our configuration, we -have to first add: +Or we could use the repository's web interface (implemented by \c{brep}). Our +repository has one, check it out: \c{\l{https://build2.org/pkg/hello/}}. + +Ok, back to the command line. If we want to use a repository as a source of +packages in our configuration, we have to first add it: \ $ bpkg add https://build2.org/pkg/1/hello/stable added repository build2.org/hello/stable \ -If we want to add several repositories, we just execute the \c{add} command for -each of them. Once this is done, we fetch the list of available packages for -all the added repositories: +If we want to add several repositories, we just execute the \l{bpkg-cfg-add(1) +\c{brep add}} command for each of them. Once this is done, we fetch the list of +available packages for all the added repositories: \ $ bpkg fetch @@ -211,8 +211,9 @@ fetching build2.org/hello/stable 2 package(s) in 1 repository(s) \ -You would normally re-run the \c{fetch} command after you've added another -repository or to refresh the list of available packages. +You would normally re-run the \l{bpkg-cfg-fetch(1) \c{bpkg fetch}} command +after you've added another repository or to refresh the list of available +packages. Now that \c{bpkg} knows where to get packages, we can finally get down to business: @@ -224,20 +225,20 @@ build hello 1.0.0 continue? [Y/n] \ -Let's see what's going on here. We asked \c{bpkg} to build the \c{hello} -program which happens to depend on the \c{libhello} library. So \c{bpkg} -presents us with a \i{plan of action} that it will have to perform in order to -build us \c{hello} and then asks us to confirm that's what we want to do (you -can add \c{--yes|-y} to skip the confirmation). Let's answer \i{yes} and see -what happens: +Let's see what's going on here. We ran \l{bpkg-pkg-build(1) \c{bpkg build}} to +build the \c{hello} program which happens to depend on the \c{libhello} +library. So \c{bpkg} presents us with a \i{plan of action}, that is, the steps +it will have to perform in order to build us \c{hello} and then asks us to +confirm that's what we want to do (you can add \c{--yes|-y} to skip the +confirmation). Let's answer \i{yes} and see what happens: \ ... continue? [Y/n] y -libhello-1.0.0+1.tar.gz 100% of 1489 B 1364 kBps 00m01s +libhello-1.0.0+1.tar.gz 100% of 1489 B 1364 kBps 00m01s fetched libhello 1.0.0+1 unpacked libhello 1.0.0+1 -hello-1.0.0.tar.gz 100% of 1030 B 20 MBps 00m01s +hello-1.0.0.tar.gz 100% of 1030 B 20 MBps 00m01s fetched hello 1.0.0 unpacked hello 1.0.0 configured libhello 1.0.0+1 @@ -254,9 +255,9 @@ unpacked, and configured both packages and then proceeded to building the \c{hello} executable which happens to require building of the \c{libhello} library. Note that the download progress may look differently on your machine depending on which \i{fetch tool} (\c{wget}, \c{curl}, or \c{fetch}) is -used. If you ever considered giving that \c{-v} option a try, now would be good -time. But let's first drop the \c{hello} package so that we get the same -build from scratch: +used. If you ever considered giving that \c{-v} option a try, now would be a +good time. But let's first drop (\l{bpkg-pkg-build(1) \c{bpkg drop}}) the +\c{hello} package so that we get the same build from scratch: \ $ bpkg drop hello @@ -308,10 +309,10 @@ g++-5 -O3 -std=c++11 -o hello-1.0.0/hello hello-1.0.0/hello.o libhello-1.0.0+1/h updated hello 1.0.0 \ -Another handy \c{bpkg} command is \c{status}. It can be used to examine the -state of a package in the configuration. Here are a few examples (if you -absolutely must know what \c{hold_package} means, check the -\l{bpkg-pkg-status(1)} man page): +Another handy command is \l{bpkg-pkg-status(1) \c{bpkg status}}. It can be used +to examine the state of a package in the configuration. Here are a few examples +(if you absolutely must know what \c{hold_package} means, check the +command's documentation): \ $ bpkg status libhello @@ -405,13 +406,13 @@ Let's answer \i{yes} if only to see what happens: continue? [Y/n] y disfigured hello 1.0.0 disfigured libhello 1.0.0+1 -libformat-1.0.0.tar.gz 100% of 1064 B 11 MBps 00m01s +libformat-1.0.0.tar.gz 100% of 1064 B 11 MBps 00m01s fetched libformat 1.0.0 unpacked libformat 1.0.0 -libprint-1.0.0.tar.gz 100% of 1040 B 9 MBps 00m01s +libprint-1.0.0.tar.gz 100% of 1040 B 9 MBps 00m01s fetched libprint 1.0.0 unpacked libprint 1.0.0 -libhello-1.1.0.tar.gz 100% of 1564 B 4672 kBps 00m01s +libhello-1.1.0.tar.gz 100% of 1564 B 4672 kBps 00m01s fetched libhello 1.1.0 unpacked libhello 1.1.0 configured libformat 1.0.0 @@ -440,7 +441,7 @@ surprising: the \c{hello} package wasn't \i{updated}. Yes, it was reconfigured, but we didn't see any compile or link commands for this project. In fact, \c{hello} is now pretty \i{out-of-date}. -While it may seem surprising, \c{bpkg} doesn't try to keep your packages +While it may sound surprising, \c{bpkg} doesn't try to keep your packages \i{up-to-date}. Configured \- yes, but not up-to-date. Trying to guarantee up-to-date-ness of packages is in the end futile. For example, if you upgrade your compiler or system headers, \c{bpkg} has no way of realizing that some @@ -448,8 +449,9 @@ packages are now out-of-date. Only the build system, which has the complete information about all the dependencies, can make such a realization (and correct it). -But it is easy to make sure a package is up-to-date at any given time with -the \c{bpkg update} command (there is also \c{clean}), for example: +But it is easy to make sure a package is up-to-date at any given time with the +\l{bpkg-pkg-update(1) \c{bpkg update}} command (there is also +\l{bpkg-pkg-clean(1) \c{bpkg clean}}), for example: \ $ bpkg update hello @@ -460,8 +462,8 @@ updated hello 1.0.0 Let's say we really don't like the direction \c{libhello} is going and would rather stick to version \c{1.0.0}. Just like upgrades, downgrades are -explicit except in this case we need to specify the version (you -can also specify the version for upgrades, in case you are wondering). +explicit plus, in this case, we need to specify the version (you +can also specify desired version for upgrades, in case you are wondering). \ $ bpkg build libhello/1.0.0 hello @@ -470,7 +472,7 @@ reconfigure/build hello 1.0.0 continue? [Y/n] y disfigured hello 1.0.0 disfigured libhello 1.1.0 -libhello-1.0.0+1.tar.gz 100% of 1489 B 983 kBps 00m01s +libhello-1.0.0+1.tar.gz 100% of 1489 B 983 kBps 00m01s fetched libhello 1.0.0+1 unpacked libhello 1.0.0+1 configured libhello 1.0.0+1 @@ -487,16 +489,17 @@ ld hello-1.0.0/exe{hello} updated hello 1.0.0 \ -Notice how this time we updated \c{hello} as part of \c{libhello} downgrade \- -yes, you can do that. Perhaps there should be an option to automatically update -all the dependents? +Notice how this time we updated \c{hello} as part of the \c{libhello} downgrade +\- yes, you can do that. Perhaps there should be an option to automatically +update all the dependents? Ok, so all this might look nice and all, but we haven't actually seen anything of what we've presumably built (it can all be a charade, for all we know). Can we see some libraries and run the \c{hello} program? There are several ways we can do this. If the package provides tests (as all -good packages should), we can run them with the \c{bpkg test} command: +good packages should), we can run them with the \l{bpkg-pkg-test(1) \c{bpkg +test}} command: \ $ bpkg test libhello hello @@ -545,13 +548,13 @@ $ hello-1.0.0/hello World Hello, World! \ -The important point here is that the \c{bpkg} configuration is not some black +The important point here is this: the \c{bpkg} configuration is not some black box that you should never look inside. On the contrary, it is a normal building block of the build system and if you understand what you are doing, feel free to muck around. Now, confess, did you run \c{sqlite3 bpkg.sqlite3 .dump}? -Another way to get hold of a package's goodies is to install it. Let's try -that: +Another way to get hold of a package's goodies is to install it with +\l{bpkg-pkg-install(1) \c{bpkg install}}. Let's try that: \ $ bpkg install config.install.root=/opt/hello \ @@ -586,7 +589,7 @@ Hello, World! \ The \c{config.install.root.sudo} value is the optional \i{sudo}-like program -that should be used to run the \c{install} commands. For those feeling queasy +that should be used to run the \c{install} program. For those feeling queasy running \c{sudo make install}, here is your answer. If you are wondering whether you could have specified those \c{config.install.*} values during the configuration creation, the answer is yes, indeed! @@ -619,7 +622,8 @@ int main () \ -What build system will we use? I can't believe you are even asking! +What build system will we use? I can't believe you are even asking this +question! \ $ mkdir build @@ -675,9 +679,10 @@ info: while applying rule alias to update dir{./} \ No magic but we got a hint: looks like we need to tell \c{build2} where -\c{libhello} is with \c{config.import.libhello}. Without fretting too much +\c{libhello} using \c{config.import.libhello}. Without fretting too much about what exactly \c{out_root} means, let's point \c{build2} to our \c{bpkg} -configuration and see what happens. +configuration and see what happens. After all, that's where, more or less, +our \i{out} for \c{libhello} is. \ $ b config.import.libhello=/tmp/hello-gcc5-release @@ -718,10 +723,10 @@ info: while applying rule alias to update dir{./} \ Looks like we have to keep repeating that \c{config.import.libhello} and who -wants that? Also, the \c{test g++} line is kind of annoying. To get rid of both +wants that? Also, the \c{test g++} line is getting annoying. To get rid of both we have to make our configuration \i{permanent}. Also, seeing that we plan to have several of them (GCC/Clang, different version of \c{libhello}), it makes -sense to create them \i{out of source tree}. Let's get to it. +sense to create them \i{out of source tree}. Let's get to it: \ $ cd .. @@ -743,11 +748,11 @@ save hello2-gcc5-release/build/config.build Translated, \c{configure(hello2/@hello2-gcc5-release/)} means \i{\"configure the \c{hello2/} source directory in the \c{hello2-gcc5-release/} output directory\"}. In \c{build2} this \i{source directory} is called \c{src_root} -and \i{output directory} \- \c{out_root}. Hm, we've already seen \c{out_root} +and \i{output directory} \- \c{out_root}. Hm, we've already heard \c{out_root} mentioned somewhere before... Once the configuration is saved, we can develop our project without any -hindrance: +annoyance: \ $ b hello2-gcc5-release/ @@ -769,7 +774,7 @@ g++-5 -O3 -std=c++11 -o hello hello.o /tmp/hello-gcc5-release/libhello-1.0.0+1/h \ Some of you might have noticed that \c{hello2-gcc5-release/} and -\c{/tmp/hello-gcc5-release/} are awfully similar and are now wondering if we +\c{/tmp/hello-gcc5-release/} look awfully similar and are now wondering if we could instead build \c{hello2} \i{inside} \c{/tmp/hello-gcc5-release/}? I am glad you've asked. In fact, we can just do: @@ -794,10 +799,10 @@ ld /tmp/hello-gcc5-release/hello2/exe{hello} Now that might seem like magic, but it's actually pretty logical. Why don't we need to specify any of the \c{config.cxx} values this time? Because they are inherited from the set specified for \c{/tmp/hello-gcc5-release} when we -created the configuration with \c{bpkg create}. What about -\c{config.import.libhello}, don't we need at least that? Nope, \c{libhello} -will be found automatically since it is part of the same amalgamation as we -are. +created this configuration with \c{bpkg create}. What about +\c{config.import.libhello}, don't we need at least that? Not really \- +\c{libhello} will be found automatically since it is part of the same +amalgamation as we now are. Of course, \c{bpkg} has no idea \c{hello2} is now part of its configuration: @@ -815,8 +820,8 @@ reason why we would want that: if we upgrade \c{libhello} we would want \c{bpkg} to automatically reconfigure our project. As it is now, we will have to remember and do it ourselves. -The only way to make \c{bpkg} aware of \c{hello2} is to turn it from a -\c{build2} \i{project} into a \c{build2} \i{package}. While the topic of +The only way to make \c{bpkg} aware of \c{hello2} is to turn it from merely a +\c{build2} \i{project} into a \c{bpkg} \i{package}. While the topic of packaging is also for another time and place (the \c{build2} package manager manual), we can get away with something as simple as this: @@ -848,8 +853,9 @@ rmdir /tmp/hello-gcc5-release/hello2/build/ rmdir /tmp/hello-gcc5-release/hello2/ \ -Next, we use the \c{bpkg build} command but instead of giving it a package name -like we did before, we will point it to our \c{hello2} package directory: +Next, we use the \l{bpkg-pkg-build(1) \c{bpkg build}} command but instead of +giving it a package name like we did before, we will point it to our \c{hello2} +package directory: \ $ bpkg build -d /tmp/hello-gcc5-release/ ./hello2/ @@ -917,7 +923,7 @@ $ bpkg build libhello/1.0.0 .../hello2/ build libhello 1.0.0+1 build hello2 1.0.0 continue? [Y/n] y -libhello-1.0.0+1.tar.gz 100% of 1489 B 983 kBps 00m01s +libhello-1.0.0+1.tar.gz 100% of 1489 B 983 kBps 00m01s fetched libhello 1.0.0+1 unpacked libhello 1.0.0+1 unpacked hello2 1.0.0 |