From df6459754bd8996beec84188d2430ace421d33b6 Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Thu, 16 Jul 2020 07:32:06 +0200 Subject: Documentation updates --- doc/intro.cli | 77 +++++++++++++++++++++++++++++++++++++++++++---------------- 1 file 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. \ / @@ -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 \ -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 \ | -- cgit v1.1