1 files changed, 94 insertions, 0 deletions
diff --git a/src/boost/tools/build/example/variant/readme.qbk b/src/boost/tools/build/example/variant/readme.qbk
new file mode 100644
index 000000000..663219e34
--- /dev/null
+++ b/src/boost/tools/build/example/variant/readme.qbk
@@ -0,0 +1,94 @@
+[/
+Copyright 2004 Vladimir Prus
+Copyright 2017 Rene Rivera
+Distributed under the Boost Software License, Version 1.0.
+(See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)
+/]
+
+[section Build Variants]
+
+This example shows how user can create his own build variants. Two variants are
+defined: "crazy", which is just a random combination of properties, and
+"super-release", which is inherited from "release", and differs by a single
+define.
+
+Files:
+
+* [@../../example/variant/a.cpp a.cpp]
+* [@../../example/variant/jamroot.jam jamroot.jam]
+* [@../../example/variant/jamfile.jam jamfile.jam]
+* [@../../example/variant/libs/jamfile.jam libs/jamfile.jam]
+* [@../../example/variant/libs/l.cpp libs/l.cpp]
+
+[import jamroot.jam]
+[import jamfile.jam]
+[import libs/jamfile.jam]
+
+In this project the `jamroot.jam` specifies the custom build variants and the
+targets are specified in the two `jamfile.jam` files.
+
+[jamroot]
+
+The top-level `jamfile.jam`:
+
+[jamfile]
+
+And the library `jamfile.jam` that the top-level `jamfile.jam` refers to:
+
+[libs_jamfile]
+
+Building the example yields:
+
+[teletype]
+```
+> cd /example/variant
+> b2
+...found 20 targets...
+...updating 16 targets...
+common.mkdir bin
+common.mkdir bin/clang-darwin-4.2.1
+common.mkdir bin/clang-darwin-4.2.1/crazy
+clang-darwin.compile.c++ bin/clang-darwin-4.2.1/crazy/a.o
+common.mkdir libs/bin
+common.mkdir libs/bin/clang-darwin-4.2.1
+common.mkdir libs/bin/clang-darwin-4.2.1/crazy
+clang-darwin.compile.c++ libs/bin/clang-darwin-4.2.1/crazy/l.o
+clang-darwin.link.dll libs/bin/clang-darwin-4.2.1/crazy/libl.dylib
+clang-darwin.link bin/clang-darwin-4.2.1/crazy/a
+common.mkdir bin/clang-darwin-4.2.1/super_release
+clang-darwin.compile.c++ bin/clang-darwin-4.2.1/super_release/a.o
+common.mkdir libs/bin/clang-darwin-4.2.1/super_release
+clang-darwin.compile.c++ libs/bin/clang-darwin-4.2.1/super_release/l.o
+clang-darwin.link.dll libs/bin/clang-darwin-4.2.1/super_release/libl.dylib
+clang-darwin.link bin/clang-darwin-4.2.1/super_release/a
+...updated 16 targets...
+```
+
+As specified in the top-level `jamfile.jam` both custom variants where built
+by default. Once can override that by specifying the variant one wants to
+build directly on the command line with a `variant=super_release`. Or just
+with a `super_release` as variants can be referred to by their name only.
+For example using that argument yields:
+
+```
+> cd /example/variant
+> b2 super_release
+...found 14 targets...
+...updating 10 targets...
+common.mkdir bin
+common.mkdir bin/clang-darwin-4.2.1
+common.mkdir bin/clang-darwin-4.2.1/super_release
+clang-darwin.compile.c++ bin/clang-darwin-4.2.1/super_release/a.o
+common.mkdir libs/bin
+common.mkdir libs/bin/clang-darwin-4.2.1
+common.mkdir libs/bin/clang-darwin-4.2.1/super_release
+clang-darwin.compile.c++ libs/bin/clang-darwin-4.2.1/super_release/l.o
+clang-darwin.link.dll libs/bin/clang-darwin-4.2.1/super_release/libl.dylib
+clang-darwin.link bin/clang-darwin-4.2.1/super_release/a
+...updated 10 targets...
+```
+
+[note The actual paths in the `bin` sub-directory will depend on your
+toolset.]
+
+[endsect]