aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2020-07-16 07:32:06 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2020-07-16 07:32:06 +0200
commitdf6459754bd8996beec84188d2430ace421d33b6 (patch)
tree6256f863f0a022934557b5a0f7f3a38889d14f11
parentae557c5b7d9ee3d21898ae9f922fad64112c145c (diff)
Documentation updates
-rw-r--r--doc/intro.cli77
1 files changed, 56 insertions, 21 deletions
diff --git a/doc/intro.cli b/doc/intro.cli
index 795b65e..b5e839a 100644
--- a/doc/intro.cli
+++ b/doc/intro.cli
@@ -169,10 +169,13 @@ hello/
└── repositories.manifest
\
-\N|While the canonical project structure is strongly recommended, especially
-for new projects, \c{build2} is flexible enough to allow most commonly used
-arrangements. See \l{#proj-struct Canonical Project Structure} for the more
-detailed discussion and rationale behind this layout.|
+\N|See \l{#proj-struct Canonical Project Structure} for a detailed discussion
+and rationale behind this layout. While it is recommended, especially for new
+projects, \c{build2} is flexible enough to support various arrangements used
+in today's C and C++ projects. Furthermore, the \l{bdep-new(1)} command
+provides a number of customization options and chances are you will be able to
+create your preferred layout automatically. See \l{bdep-new.xhtml#src-layout
+SOURCE LAYOUT} for more information and examples.|
Similar to version control tools, we normally run all \c{build2} tools from
the project's source directory or one of its subdirectories, so:
@@ -1629,9 +1632,32 @@ hello/
libhello/
hello-gcc/
hello-clang/
+
+$ tree libhello
+libhello/
+├── build/
+│ └── ...
+├── libhello/
+│ ├── hello.hxx
+│ ├── hello.cxx
+│ └── buildfile
+├── buildfile
+├── manifest
+├── README.md
+└── repositories.manifest
+\
+
+\N|Similar to the executable project, this layout is not mandatory and
+\l{bdep-new(1)} can create a number of alternative library structures. For
+example, if you prefer the \c{include/src} split, try:
+
+\
+$ bdep new -l c++ -t lib,split libhello
\
-Let's also edit the generated \c{manifest} file and add the \c{project} value
+See \l{bdep-new.xhtml#src-layout SOURCE LAYOUT} for more examples.|
+
+Let's edit the generated \c{manifest} file and add the \c{project} value
(customarily after \c{version}) to indicate that our library belongs to the
same overall project as our executable:
@@ -2295,12 +2321,21 @@ entry as a documentation to users of our project.|
\h1#proj-struct|Canonical Project Structure|
-The goal of establishing a canonical project structure is to create an
-ecosystem of packages that can coexist, are easy to comprehend by both humans
-and tools, scale to complex, real-world requirements, and, last but not least,
-are pleasant to work with.
-
-The canonical structure is primarily meant for a package \- a single library
+The goal of establishing a canonical \c{build2} project structure is to create
+an ecosystem of packages that can coexist, are easy to comprehend by both
+humans and tools, scale to complex, real-world requirements, and, last but not
+least, are pleasant to work with.
+
+\N|Here by \i{canonical} we mean a structure that on balance achieves these
+objectives in the simplest possible way. However, not everyone agrees with
+where that balance should be struck. As a result, this structure is only
+recommended and \c{build2} is flexible enough to support various arrangements
+used in modern C and C++ projects. Furthermore, the \l{bdep-new(1)} command
+provides a number of customization options and chances are you will be able to
+create your preferred layout automatically. See \l{bdep-new.xhtml#src-layout
+SOURCE LAYOUT} for more information and examples.|
+
+This canonical structure is primarily meant for a package \- a single library
or program (or, sometimes, a collection of related libraries or programs)
with a specific and well-defined function. While it may be less suitable for
more elaborate, multi-library/program \i{end-products} that are not meant to
@@ -2314,12 +2349,11 @@ end-products and into separate packages, for example, in order to be reused in
another end-product). In this light, it can be helpful to organize a new
end-product project as a composition of individual packages or source
subdirectories that follow the canonical structure. The \l{bdep-new(1)}
-\c{--package} and \c{--subdirectory} modes can be used to automate this
-process.|
+\c{--package} and \c{--source} modes can be used to automate this process.|
-Projects created by the \l{bdep-new(1)} command have the canonical structure.
-The overall layouts for executable (\c{-t\ exe}) and library (\c{-t\ lib})
-projects are presented below.
+By default, projects created by the \l{bdep-new(1)} command have the canonical
+structure. The overall layouts for executable (\c{-t\ exe}) and library
+(\c{-t\ lib}) projects are presented below.
\
<name>/
@@ -2378,7 +2412,7 @@ If a project consists of a library and an executable, then they should be
split into separate packages (see \l{#guide-dev-multi Developing Multiple
Packages and Projects} for some common arrangements). In this case, by
convention, the library name should start with the \c{lib} prefix, for
-example, \c{libhello} and \c{hello}. It is also strongly recommended (but not
+example, \c{libhello} and \c{hello}. It is also recommended (but not
required) to follow this convention in new projects, even if there are no
plans to have a related executable.
@@ -2478,10 +2512,11 @@ except that in the case of modules calling the directory \c{include/} would be
an anachronism.
To summarize, the split directory arrangement offers little benefit over the
-single directory layout, has a number of real drawbacks, and does not fit
+combined directory layout, has a number of real drawbacks, and does not fit
modularized projects well. In practice, private headers are placed into
\c{include/}, often either in a subdirectory or with a special file name
-suffix, a mechanism that is readily available in the single directory layout.|
+suffix, a mechanism that is readily available in the combined directory
+layout.|
All headers within a project should be included using the \c{<>} style
inclusion and contain the project name as a directory prefix. And all headers
@@ -2602,12 +2637,12 @@ With the header inclusion paths adjusted accordingly:
#include <libstud/url/url.hxx>
\
-The \l{bdep-new(1)} command provides the \c{source} project type sub-option
+The \l{bdep-new(1)} command provides the \c{subdir} project type sub-option
that allows us to customize the source subdirectory within a project. For
example:
\
-$ bdep new -l c++ -t lib,source=libstud/path libstud-path
+$ bdep new -l c++ -t lib,subdir=libstud/path libstud-path
\
|