From 1845141809aa91b03718066a6f46863885a6a887 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Thu, 7 Mar 2019 09:06:37 +0200
Subject: Add support for alternative build file/directory naming scheme

Now the build/*.build, buildfile, and .buildignore filesystem entries in
a project can alternatively (but consistently) be called build2/*.build2,
build2file, and .build2ignore. See a note at the beginning of the Project
Structure section in the manual for details (motivation, restrictions,
etc).
---
 doc/manual.cli | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

(limited to 'doc')

diff --git a/doc/manual.cli b/doc/manual.cli
index 2ac3b8f..15d7c31 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -459,6 +459,41 @@ $ bdep new --no-init -t exe -l c++,cpp hello
 
 |
 
+\N|It is also possible to use an alternative build file/directory naming
+scheme where every instance of the word \i{build} is replaced with \i{build2},
+for example:
+
+\
+hello/
+├── build2/
+│   ├── bootstrap.build2
+│   └── root.build2
+├── ...
+└── build2file
+\
+
+Note that the naming must be consistent within a project with all the
+filesystem entries either following \i{build} or \i{build2} scheme. In
+other words, we cannot call the directory \c{build2/} while still using
+\c{buildfile}.
+
+The alternative naming scheme is primarily useful when adding \c{build2}
+support to an existing project along with other build systems. In this case,
+the fairly generic standard names might already be in use. For example, it is
+customary to have \c{build/} in \c{.gitignore}. Plus more specific naming will
+make it easier to identify files and directories as belonging to the
+\c{build2} support. For new projects as well as for existing projects that are
+switching exclusively to \c{build2} the standard naming scheme is recommended.
+
+To create a project with the alternative naming using \l{bdep-new(1)} pass
+the \c{alt-naming} project type sub-option. For example:
+
+\
+$ bdep new -t exe,alt-naming ...
+\
+
+|
+
 To support lazy loading of subprojects (discussed later), reading of the
 project's build information is split into two phases: bootstrapping and
 loading. During bootstrapping the project's \c{build/bootstrap.build} file is
-- 
cgit v1.1