Use Cases

The following examples illustrate a few tasks you can achieve using the sandbox template by executing the file_template.py script from the template-under-construction directory of the Boost Sandbox.

To start a new sandbox project (the script will ask you for any required information):

python file_template.py sandbox

sandbox specifies the root directory of the template.

To start a new sandbox project and provide the required information in the command line:

python file_template.py sandbox library=my_library "authors=John J. Doe"

library and authors are sandbox options.

Tip

To include an author with multiple last names, use the _ character instead of spaces (e.g., "authors=Jan De_Man")

To place the result in a particular destination directory:

python file_template.py destination=/boost_sandbox sandbox

destination is a global option, and specifies where the result is constructed.

Warning

The following use cases are works in progress, and will produce half-baked results. In, particular, generated Xcode IDE projects should contain the correct Targets to invoke bjam on docs, tests, and examples, but they will not reference any of the source files in the project. Also, any existing code integrated into the template (last listed use case) will be intelligently recognized by only some parts of the sandbox template.

To start a new sandbox project with the optional Xcode and MSVC IDE projects and a non-default documentation format:

python file_template.py sandbox library=file_template "authors=Stjepan Rajko" docs=qb xcodeide=y vc8ide=y

docs, xcodeide and vc8ide are sandbox options.

To integrate existing code into a new sandbox project:

python file_template.py sandbox library=my_library "authors=John Doe,Jane Dough" fignore=.hpp fignore=.cpp
    (...)          /path/to/existing/my_library into=my_library

fignore is a template option which will cause the processor to ignore any files in the sandbox template with the specified suffix. into specifies that the existing my_library code should go into the my_library directory of the destination tree.

This assumes that any content under =/path/to/existing/my_library has a structure compatibile with the sandbox template, i.e. something like:

/boost
  /my_library
 /libs
  /my_library
   /doc
   /test
   ...

If my_library was the only thing inside /path/to/existing, we chould just use /path/to/existing as the template, and omit the into template option.

For more information...

sandbox options reference
sandbox substitution templates reference
links to helpful outside documentation

Output of a sample session

python.exe file_template.py sandbox
/-------------------------------------------
| Processing template sandbox with options:
+---
|| {'ignore': set([]), 'template': 'sandbox'}
|/-------------------------------------------
|| Examining the template project tree...
|+---
|||
||/-------------------------------------------
||| Welcome to the Boost Sandbox template.
||+---
||/-------------------------------------------
||| Enter value for option library:
||+---
||| (all lowercase, use underscores to separate words, e.g. "my_library"): my_library
||/-------------------------------------------
||| Enter value for option authors:
||+---
||| (comma separated, no spaces outside names, e.g., "My Name,Notmy R. Name": Stjepan Rajko
||| $template_library$
||| $template_library$/boost
||| $template_library$/boost/$template_library$
||| $template_library$/libs
||| $template_library$/libs/$template_library$
||| $template_library$/libs/$template_library$/build
||| $template_library$/libs/$template_library$/test
||| $template_library$/libs/$template_library$/doc
||| $template_library$/libs/$template_library$/doc\html
||| $template_library$/libs/$template_library$/doc/html/images
||| $template_library$/libs/$template_library$/src
||| $template_library$/libs/$template_library$/example
/-------------------------------------------
| Preparing destination tree...
+---
|/-------------------------------------------
|| Directories:
|+---
|| my_library
|| my_library/boost
|| my_library/libs
|| my_library/boost/my_library
|| my_library/libs/my_library
|| my_library/libs/my_library/build
|| my_library/libs/my_library/test
|| my_library/libs/my_library/doc
|| my_library/libs/my_library/src
|| my_library/libs/my_library/example
|| my_library/libs/my_library/doc/html
|| my_library/libs/my_library/doc/html/images
|/-------------------------------------------
|| Files:
|+---
|| my_library/LICENSE_1_0.txt
|| my_library/boost-build.jam
|| my_library/Jamfile.v2
|| my_library/project-root.jam
|| my_library/boost/my_library.hpp
|| my_library/boost/my_library/my_library.hpp
|| my_library/libs/my_library/test/test.cpp
|| my_library/libs/my_library/test/Jamfile.v2
|| my_library/libs/my_library/doc/html/reference.css
|| my_library/libs/my_library/doc/html/boostbook.css
|| my_library/libs/my_library/doc/html/images/prev.png
|| my_library/libs/my_library/doc/html/images/tip.png
|| my_library/libs/my_library/doc/html/images/important.png
|| my_library/libs/my_library/doc/html/images/next.png
|| my_library/libs/my_library/doc/html/images/toc-minus.png
|| my_library/libs/my_library/doc/html/images/draft.png
|| my_library/libs/my_library/doc/html/images/caution.png
|| my_library/libs/my_library/doc/html/images/Thumbs.db
|| my_library/libs/my_library/doc/html/images/up.png
|| my_library/libs/my_library/doc/html/images/note.png
|| my_library/libs/my_library/doc/html/images/warning.png
|| my_library/libs/my_library/doc/html/images/toc-plus.png
|| my_library/libs/my_library/doc/html/images/blank.png
|| my_library/libs/my_library/doc/html/images/home.png
|| my_library/libs/my_library/doc/html/images/toc-blank.png
|| my_library/libs/my_library/example/example.cpp
|| my_library/libs/my_library/example/Jamfile.v2
|| my_library/libs/my_library/doc/my_library.qbk
|| my_library/libs/my_library/doc/Jamfile.v2
/-------------------------------------------
| Creating file tree from template...
+---
|/-------------------------------------------
|| Python files...
|+---
||| ./my_library/libs/my_library/doc/my_library.qbk
||| ./my_library/libs/my_library/doc/Jamfile.v2
|/-------------------------------------------
|| Files...
|+---
||| ./my_library/LICENSE_1_0.txt
||| ./my_library/boost-build.jam
||| ./my_library/Jamfile.v2
||| ./my_library/project-root.jam
||| ./my_library/boost/my_library.hpp
||| ./my_library/boost/my_library/my_library.hpp
||| ./my_library/libs/my_library/test/test.cpp
||| ./my_library/libs/my_library/test/Jamfile.v2
||| ./my_library/libs/my_library/doc/html/reference.css
||| ./my_library/libs/my_library/doc/html/boostbook.css
||| ./my_library/libs/my_library/doc/html/images/prev.png
||| ./my_library/libs/my_library/doc/html/images/tip.png
||| ./my_library/libs/my_library/doc/html/images/important.png
||| ./my_library/libs/my_library/doc/html/images/next.png
||| ./my_library/libs/my_library/doc/html/images/toc-minus.png
||| ./my_library/libs/my_library/doc/html/images/draft.png
||| ./my_library/libs/my_library/doc/html/images/caution.png
||| ./my_library/libs/my_library/doc/html/images/Thumbs.db
||| ./my_library/libs/my_library/doc/html/images/up.png
||| ./my_library/libs/my_library/doc/html/images/note.png
||| ./my_library/libs/my_library/doc/html/images/warning.png
||| ./my_library/libs/my_library/doc/html/images/toc-plus.png
||| ./my_library/libs/my_library/doc/html/images/blank.png
||| ./my_library/libs/my_library/doc/html/images/home.png
||| ./my_library/libs/my_library/doc/html/images/toc-blank.png
||| ./my_library/libs/my_library/example/example.cpp
||| ./my_library/libs/my_library/example/Jamfile.v2