aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2018-03-30 10:03:11 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2018-03-30 10:03:11 +0200
commit4d0d7321806d72252521e227a27afd6d8e06a887 (patch)
tree13d528ed313c3c5866a120458e2d7eb2f8a1f85f
parentc4d8116334a3fb235f729566b1095112aa2ac9cb (diff)
Update documentation
-rw-r--r--bdep/bdep.cli119
-rwxr-xr-xdoc/cli.sh2
2 files changed, 115 insertions, 6 deletions
diff --git a/bdep/bdep.cli b/bdep/bdep.cli
index 738d00a..d13a22d 100644
--- a/bdep/bdep.cli
+++ b/bdep/bdep.cli
@@ -38,7 +38,113 @@ namespace bdep
{
"",
"",
- "
+ "A \cb{bdep} project is a directory, normally under a version control
+ system such as \cb{git(1)}, called \i{project repository}. A project
+ contains one or more \i{packages}. If it contain several, then they are
+ normally related, for example, the \cb{libhello} library and the
+ \cb{hello} program.
+
+ Packages in a project may depend on other packages outside of the
+ project. To distinguish between the two we call them \i{project packages}
+ and \i{dependency packages}, respectively. Naturally, our project
+ packages may be someone else's dependency packages.
+
+ A simple, single-package project contains the package in the root of the
+ project repository. For example (note the location of the package
+ \cb{manifest} and \cb{lockfile}):
+
+ \
+ hello/
+ ├── .git/
+ ├── ...
+ ├── lockfile
+ └── manifest
+ \
+
+ See \l{bpkg#manifest-package Package Manifest} for details on the
+ \cb{manifest} file.
+
+ If a project contains multiple packages or we wish to place the package
+ into a subdirectory, then the root of the project repository must
+ contain the \cb{packages.manifest} file that specifies the package
+ locations. For example:
+
+ \
+ hello/
+ ├── .git/
+ ├── hello/
+ │   ├── ...
+ │   ├── lockfile
+ │   └── manifest
+ ├── libhello/
+ │   ├── ...
+ │   ├── lockfile
+ │   └── manifest
+ └── packages.manifest
+ \
+
+ For this project, \cb{packages.manifest} would have the following
+ contents:
+
+ \
+ : 1
+ location: hello/
+ :
+ location: libhello/
+ \
+
+ A project repository root would usually also contain the
+ \cb{repositories.manifest} file that lists the repositories that provide
+ the dependency packages. For example:
+
+ \
+ hello/
+ ├── ...
+ ├── manifest
+ └── repositories.manifest
+ \
+
+ If our \cb{hello} project wanted to use \cb{libhello} as a dependency
+ package, then \cb{repositories.manifest} could look like this:
+
+ \
+ : 1
+ role: prerequisite
+ location: https://example.com/libhello.git
+ :
+ role: base
+ summary: hello project repository
+ \
+
+ See \l{bpkg#manifest-repository-list Repository List Manifest} for
+ details on the \cb{repositories.manifest} file.
+
+ For development a \cb{bdep} project is associated with one or more
+ \l{bpkg(1)} \i{build configurations}. These configuration are used as a
+ \i{backing} for building project packages and their dependencies.
+
+ The list of the associated build configuration as well as the list of
+ project packages initialized in each such configuration are stored in
+ the \cb{bdep} \i{project database} under the \cb{.bdep/} subdirectory
+ of the project root directory. For example:
+
+ \
+ hello-gcc/ # Build configuration for gcc.
+ hello-clang/ # Build configuration for clang.
+ hello/
+ ├── .bdep/
+ ├── .git/
+ └── ...
+ \
+
+ The core of \cb{bdep} functionality is \i{state synchronization} between
+ the project and one or more associated build configurations. For example,
+ if we list a new dependency in the package's \cb{manifest} file, then
+ \cb{bdep} fetches and configures this dependency in a build
+ configuration. Similarly, if we upgrade a dependency in a build
+ configuration, then \cb{bdep} updates the corresponding entry in the
+ package's \cb{lockfile}.
+
A typical \cb{bdep} workflow would consist of the following steps.
\dl|
@@ -52,8 +158,8 @@ namespace bdep
$ git clone ssh://example.com/hello.git
\
- Alternatively, we can use the \l{bdep-new(1)} command to create a
- sample project:
+ Alternatively, we can use the \l{bdep-new(1)} command to start a new
+ project:
\
$ bdep new -t exe -l c++ hello
@@ -139,8 +245,8 @@ namespace bdep
...
\
- If we now run \l{bdep-status(1)}, we will notice that a new iteration
- of our project is available for synchronization:
+ If we now run \l{bdep-status(1)}, we will notice that a new
+ \i{iteration} of our project is available for synchronization:
\
$ bdep status
@@ -148,7 +254,8 @@ namespace bdep
available 0.1.0-a.0.19700101000000#1
\
- |
+ See \l{bpkg#package-version Package Version} for details on package
+ versions and iterations.|
\li|\b{Synchronize the Project with Configurations}\n
diff --git a/doc/cli.sh b/doc/cli.sh
index 48a8b74..fb19aa2 100755
--- a/doc/cli.sh
+++ b/doc/cli.sh
@@ -40,12 +40,14 @@ function compile ()
--include-base-last "${o[@]}" --generate-html --html-prologue-file \
man-prologue.xhtml --html-epilogue-file man-epilogue.xhtml --html-suffix .xhtml \
--link-regex '%bpkg([-.].+)%../../bpkg/doc/bpkg$1%' \
+--link-regex '%bpkg(#.+)?%../../bpkg/doc/build2-package-manager-manual.xhtml$1%' \
--link-regex '%bdep(#.+)?%build2-project-manager-manual.xhtml$1%' \
../bdep/$n.cli
cli -I .. -v project="bdep" -v version="$version" -v date="$date" \
--include-base-last "${o[@]}" --generate-man --man-prologue-file \
man-prologue.1 --man-epilogue-file man-epilogue.1 --man-suffix .1 \
+--link-regex '%bpkg(#.+)?%$1%' \
--link-regex '%bdep(#.+)?%$1%' \
../bdep/$n.cli
}