aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rwxr-xr-xdoc/cli.sh1
-rw-r--r--doc/intro2.cli113
2 files changed, 95 insertions, 19 deletions
diff --git a/doc/cli.sh b/doc/cli.sh
index 6d99c25..1747730 100755
--- a/doc/cli.sh
+++ b/doc/cli.sh
@@ -39,6 +39,7 @@ function gen () # <name>
--link-regex '%bdep([-.].+)%../../bdep/doc/bdep$1%' \
--link-regex '%b(#.+)?%../../build2/doc/build2-build-system-manual.xhtml$1%' \
--link-regex '%bpkg(#.+)?%../../bpkg/doc/build2-package-manager-manual.xhtml$1%' \
+--link-regex '%testscript(#.+)?%../../build2/doc/build2-testscript-manual.xhtml$1%' \
--output-prefix build2-toolchain- "${@}" $n.cli
html2ps -f doc.html2ps:a4.html2ps -o build2-toolchain-$n-a4.ps build2-toolchain-$n.xhtml
diff --git a/doc/intro2.cli b/doc/intro2.cli
index 1d62ee6..69cfbee 100644
--- a/doc/intro2.cli
+++ b/doc/intro2.cli
@@ -39,7 +39,7 @@ $ b
$ ./hello
$ edit repositories.manifest # add https://example.org/libhello.git
-$ edit manifest # add 'depends: libhello ^ 1.0.0'
+$ edit manifest # add 'depends: libhello ^1.0.0'
$ edit buildfile # import libhello
$ edit hello.cxx # use libhello
$ b
@@ -108,8 +108,9 @@ hello/
├── .bdep/
├── build/
├── hello/
+│   ├── hello.cxx
│   ├── buildfile
-│   └── hello.cxx
+│   └── testscript
├── buildfile
├── manifest
└── repositories.manifest
@@ -135,9 +136,17 @@ $ cat hello/hello.cxx
#include <iostream>
-int main ()
+using namespace std;
+
+int main (int argc, char* argv[])
{
- std::cout << \"Hello, World!\" << std::endl;
+ if (argc < 2)
+ {
+ cerr << \"error: missing name\" << endl;
+ return 1;
+ }
+
+ cout << \"Hello, \" << argv[1] << '!' << endl;
}
\
@@ -153,7 +162,7 @@ $ cat hello/buildfile
libs =
#import libs += libhello%lib{hello}
-exe{hello}: {hxx ixx txx cxx}{*} $libs
+exe{hello}: {hxx ixx txx cxx}{*} $libs test{testscript}
\
As the name suggests, this file describes how to build things. While its
@@ -161,12 +170,33 @@ content might look a bit cryptic, let's try infer a couple of points without
going into too much detail (the details are discussed in the following
sections). That \c{exe{hello\}} on the left of \c{:} is a \i{target}
(executable named \c{hello}) and what we have on the right are
-\i{prerequisites} (C++ sources files). This \c{buildfile} uses
+\i{prerequisites} (C++ sources files, libraries, etc). This \c{buildfile} uses
\l{b#name-patterns wildcard patterns} (that \c{*}) to automatically locate all
-the source files. This means we don't have to edit our \c{buildfile} every
+the C++ source files. This means we don't have to edit our \c{buildfile} every
time we add a source file to our project. There also appears to be some
infrastructure for importing (commented out) and linking libraries (that
-\c{libs} variable). We will see how to use it in a moment.
+\c{libs} variable). We will see how to use it in a moment. Finally,
+\c{buildfile} also lists \c{testscript} as a prerequisite of \c{hello}. This
+file tests our program. Let's take a look inside:
+
+\
+: basics
+:
+$* 'World' >'Hello, World!'
+
+: missing-name
+:
+$* 2>>EOE != 0
+error: missing name
+EOE
+\
+
+Again, we are not going into detail here (see \l{testscript#intro Testscript
+Introduction} for a proper introduction), but to give you an idea, here we
+have two tests: the first (with id \c{basics}) verifies that our program
+prints the expected greeting while the second makes sure it handles the
+missing name error condition. Tests written in Testscript are concise,
+portable, and executed in parallel.
Next up is \c{manifest}:
@@ -179,7 +209,7 @@ summary: hello executable project
license: proprietary
url: https://example.org/hello
email: you@example.org
-#depends: libhello >= 1.0.0
+#depends: libhello ^1.0.0
\
The \c{manifest} file is what makes a build system project a \i{package}. It
@@ -301,6 +331,9 @@ hello configured 0.1.0-a.0.19700101000000
$ b
<...>
+$ b test
+<...>
+
$ hello/hello
Hello, World!
\
@@ -314,6 +347,9 @@ hello configured 0.1.0-a.0.19700101000000
$ b ../hello-clang/hello/
...
+$ b test: ../hello-clang/hello/
+...
+
$ ../hello-clang/hello/hello/hello
Hello, World!
\
@@ -399,11 +435,11 @@ build system and package manager (for example, when a build bot is building a
package for CI).
Note also that strictly speaking \c{build2} is not C/C++-specific; its build
-system is general enough to handle any DAG-based operations and its
-package/project dependency managers can be used for any compiled language.|
+model is general enough to handle any DAG-based operations and its
+package/project dependency management can be used for any compiled language.|
-\N|As we will see in moment, \c{build2} also integrates with your VCS in order
-to automate project versioning. Note that currently only \c{git(1)} is
+\N|As we will see in a moment, \c{build2} also integrates with your VCS in
+order to automate project versioning. Note that currently only \c{git(1)} is
supported.|
Let's now move on to the reason why there is \i{dep} in the \c{bdep} name:
@@ -510,14 +546,53 @@ $ bdep new -t lib -l c++ libhello
|
Next we edit the \c{manifest} file (again, found in the root of our project)
-and specify the version constraint for \c{libhello}:
+and specify the dependency on \c{libhello} with optional version constraint.
+For example:
\
-depends: libhello >= 1.0.0 (@@ ^)
+depends: libhello ^1.0.0
\
-Next we edit \c{hello/buildfile} and import the \c{libhello} library into our
-build:
+Let's discuss briefly version constraints (for details see the
+\l{bpkg#manifest-package-depends \c{depends}} value documentation). A version
+constraint can be expressed with a comparison operator (\c{==}, \c{>},
+\c{<}, \c{>=}, \c{<=}), a range shortcut operator (\c{~} and \c{^}), or a
+range. Here are a few examples:
+
+\
+depends: libhello == 1.2.3
+depends: libhello >= 1.2.3
+
+depends: libhello ~1.2.3
+depends: libhello ^1.2.3
+
+depends: libhello [1.2.3 1.2.9)
+\
+
+You may already be familiar with the tilda (\c{~}) and caret (\c{^})
+constraints from dependency managers for other languages. To recap, tilda
+allows upgrades to any further patch versions while caret also allows upgrade
+to further minor versions. They are equivalent to the following ranges:
+
+\
+~X.Y.Z [X.Y.Z X.Y+1.0)
+
+^X.Y.Z [X.Y.Z X+1.0.0) if X > 0
+^0.Y.Z [0.Y.Z 0.Y+1.0) if X == 0
+\
+
+\N|Zero major version component is customarily used during early development
+where the minor version effectively becomes major. As a result, the tilde
+constraint has a special treatment of this case.|
+
+Unless you have good reasons not to (for example, a dependency does not use
+semantic versioning) we suggest that you use the \c{^} constraint which
+provides a good balance between compatibility and upgrdability with \c{~}
+being a more conservative option.
+
+Ok, we've specified where our package comes from (\c{repositories.manifest})
+and which versions we find acceptable (\c{manifest}). The next step is to edit
+\c{hello/buildfile} and import the \c{libhello} library into our build:
\
import libs += libhello%lib{hello}
@@ -534,7 +609,7 @@ int main ()
}
\
-\N|You are probably wondering why we have to specify this often repeating
+\N|You are probably wondering why we have to specify this somewhat repeating
information in so many places. Let's start with the source code: we can't
specify the version constraint and location there because it will have
to be repeated in every source file that uses the dependency.
@@ -563,7 +638,7 @@ to your project:
\
repositories.manifest # add https://example.org/libhello.git
-manifest # add 'depends: libhello ^ 1.0.0' (@@ ^)
+manifest # add 'depends: libhello ^1.0.0'
buildfile # import libhello
hello.cxx # use libhello
\