aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2018-03-28 10:53:23 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2018-03-28 10:53:23 +0200
commitafa61b3acb7eac30c744a2be23649d51613933d2 (patch)
treeced7f1f8e0cad1585941f93771d0f38a2b8e4f62
parent584de3709037e81d821f8cc2d94fd3b87b4ae3b1 (diff)
Document typical workflow
-rw-r--r--bdep/bdep.cli175
1 files changed, 172 insertions, 3 deletions
diff --git a/bdep/bdep.cli b/bdep/bdep.cli
index 9974458..f6e2b1d 100644
--- a/bdep/bdep.cli
+++ b/bdep/bdep.cli
@@ -22,7 +22,8 @@ namespace bdep
\h|DESCRIPTION|
- The \cb{build2} project dependency manager is used to @@ TODO.
+ The \cb{build2} project dependency manager is used to manage the
+ dependencies of a project during development.
For a detailed description of any command or help topic, use the
\cb{help} command or see the corresponding man page (the man pages have
@@ -37,9 +38,177 @@ namespace bdep
{
"",
"",
+ "
+ A typical \cb{bdep} workflow would consist of the following steps.
+
+ \dl|
+
+ \li|\b{Obtain the Project}\n
+
+ Normally we would use the version control system to obtail the
+ project we want to develop:
+
+ \
+ $ git clone ssh://example.com/hello.git
+ \
+
+ Alternatively, we can use the \l{bdep-new(1)} command to create a
+ sample project:
+
+ \
+ $ bdep new -t exe -l c++ hello
+ \
+
+ Similar to version control tools, we normally run \cb{bdep} from the
+ project's directory or one of its subdirectories:
+
+ \
+ $ cd hello
+ \
+
+ See \l{bdep-projects-configs(1)} for alternative ways to specify
+ the project location.
+
+ |
+
+
+ \li|\b{Initialize the Project}\n
+
+ Next we use the \l{bdep-init(1)} command to create new or add
+ existing build configurations and initialize our project in these
+ configurations:
+
+ \
+ $ bdep init -C ../hello-gcc @gcc cc config.cxx=g++
+ $ bdep init -A ../hello-clang @clang
+ \
+
+ We can now use the \l{bdep-status(1)} command to examine the status
+ of our project in its configuration:
+
+ \
+ $ bdep status -a
+ status in configuration @gcc
+ hello configured 0.1.0-a.0.19700101000000
+
+ status in configuration @clang
+ hello configured 0.1.0-a.0.19700101000000
+ \
+
+ Most \cb{bdep} commands operate on one or more build configurations
+ associated with the project. If we don't specify one explicitly, then
+ the \i{default configuration} (usually the first added; \cb{gcc} in
+ our case) is used. Alternatively, we can specify the configurations
+ by name (if assigned), as directories, or with \c{\b{--all}|\b{-a}}
+ (see \l{bdep-projects-configs(1)} for details). For example:
+
+ \
+ $ bdep status @clang @gcc # by name
+ $ bdep status -c ../hello-gcc # as a directory
+ \
+
+ If a command is operating on multiple configurations (like \cb{status
+ -a} in the previous example), then it will print a line identifying
+ each configuration before printing the command's result.
+
+ @@ build and run?
+
+ |
+
+ \li|\b{Add, Remove, or Change Dependencies}\n
+
+ Let's say we found \cb{libhello} that we would like to use in our
+ project. First we edit our project's \cb{repositories.manifest}
+ file and add the \cb{libhello}'s repository as our prerequisite:
+
+ \
+ $ cat repositories.manifest
+ ...
+ role: prerequisite
+ location: https://example.com/libhello.git
+ ...
+ \
+
+ Next we edit our \cb{manifest} file and specify a dependency on
+ \cb{libhello}:
+
+ \
+ $ cat manifest
+ ...
+ depends: libhello >= 1.0.0
+ ...
+ \
+
+ If we now run \l{bdep-status(1)}, we will notice that a new iteration
+ of our project is available for synchronization:
+
+ \
+ $ bdep status
+ hello configured 0.1.0-a.0.19700101000000
+ available 0.1.0-a.0.19700101000000#1
+ \
+
+ |
+
+ \li|\b{Synchronize the Project with Configurations}\n
+
+ To synchronize changes in the project's dependency information with
+ its build configurations we use the \l{bdep-sync(1)} command.
+ Continuing with our example, this will result in \cb{libhello} being
+ downloaded and configured since our project now depends on it:
+
+ \
+ $ bdep sync
+
+ $ bdep status -i
+ hello configured 0.1.0-a.0.19700101000000#1
+ libhello >= 1.0.0 configured 1.0.0
+ \
+
+ |
+
+ \li|\b{Upgrade or Downgrade Dependencies}\n
+
+ The \l{bdep-sync(1)} command is also used to upgrade or downgrade
+ dependencies (and it is also executed as the last step of \cb{init}).
+ Let's say we learned a new version of \cb{libhello} was release and
+ we would like to try it out.
+
+ To refresh the list of available dependency packages we use the
+ \l{bdep-fetch(1)} command (or, as a shortcut, the \cb{-f} flag to
+ \cb{status}):
+
+ \
+ $ bdep fetch
+
+ $ bdep status libhello
+ libhello configured 1.0.0 available [1.1.0]
+ \
+
+ Without an explicit version or the \c{\b{--patch}|\b{-p}} option,
+ \cb{sync} will upgrade the specified dependency to the latest
+ available version:
+
+ \
+ $ bdep sync libhello
+
+ $ bdep status -i
+ hello configured 0.1.0-a.0.19700101000000#1
+ libhello >= 1.0.0 configured 1.1.0
+ \
+
+ Let's say we didn't like the new version and would like to go back to
+ using the old one. To downgrade a dependency we have to specify its
+ version explicitly:
+
+ \
+ $ bdep status -o libhello
+ libhello configured 1.1.0 available [1.0.0] (1.1.0)
+
+ $ bdep sync libhello/1.0.0
+ \
- //@@ TODO
- "Description...
+ ||
"
}