guyzmo/buildstrap

# Usage

```
Usage: buildstrap [-v...] [options] [run|show|debug|generate] [-p part...]<package> <requirements>...

Options:
    run                         run buildout once buildout.cfg has been generated
    show                        show the buildout.cfg (same as using `-o -`)
    debug                       print internal representation of buildout config
    generate                    create the buildout.cfg file (default action)
    <package>                   use this name for the package being developed
    <requirements>              use this requirements file as main requirements
    -p,--part <part>            choose part template to use (use "list" to show all)
    -i,--interpreter <python>   use this python version
    -o,--output <buildout.cfg>  file to output [default: buildout.cfg]
    -r,--root <path>            path to the project root (where buildout.cfg will
                be generated) (defaults to ./)
    -s,--src <path>             path to the sources (default is same as root path)
                relative to the root path if not absolute
    -e,--env <path>             path to the environment data [default: var]
                relative to directory if not absolute
    -b,--bin <path>             path to the bin directory [default: bin]
                relative to directory if not absolute
    -f,--force                  force overwrite output file if it exists
    -c,--config <path>          path to the configuration directory
                [default: ~/.config/buildstrap]
    -v,--verbose                increase verbosity
    -h,--help                   show this message
    --version                   show version
```

# Multiple requirements.txt

Many projects offer multiple `requirements.txt` files, one for each task of
the development cycle (which usually are running, testing, documenting).

Well, just tell buildstrap what the extra requirements are:

```
% buildstrap run buildstrap -p pytest -p sphinx requirements.txt requirements-doc.txt requirements-test.txt
```

and that will generate the following buildout.cfg configuration:

```
[buildout]
newest = false
parts = buildstrap
        pytest
        sphinx
package = buildstrap
extensions = gp.vcsdevelop
develop = .
eggs-directory = ${buildout:directory}/var/eggs
develop-eggs-directory = ${buildout:directory}/var/develop-eggs
parts-directory = ${buildout:directory}/var/parts
develop-dir = ${buildout:directory}/var/develop
bin-directory = ${buildout:directory}/bin
requirements = ${buildout:develop}/requirements.txt
        ${buildout:develop}/requirements-doc.txt
        ${buildout:develop}/requirements-test.txt

[buildstrap]
recipe = zc.recipe.egg
eggs = ${buildout:requirements-eggs}
        buildstrap

[pytest]
arguments = ['--cov={}/{}'.format('${buildout:develop}', package) for package in '${buildout:pack
age}'.split(',')] \
        +['--cov-report', 'term-missing', 'tests']+sys.argv[1:]
eggs = ${buildout:requirements-eggs}
recipe = zc.recipe.egg

[sphinx]
eggs = ${buildout:requirements-eggs}
source = ${buildout:directory}/doc
recipe = collective.recipe.sphinxbuilder
build = ${buildout:directory}/doc/_build
```

and you'll find all the tools you'll need in bin:

```
% ls bin
buildout    cm2html   cm2man        cm2xetex  py.test      sphinx         sphinx-autogen  sphinx-quickstart
buildstrap  cm2latex  cm2pseudoxml  cm2xml    py.test-2.7  sphinx-apidoc  sphinx-build
```

# Multiple packages

Some projects will include several packages in the sources, so to support that, just list
all your packages as a comma seperated list, and they will all be included:

```
% buildstrap show dent,prefect,beeblebox requirements.txt
[buildout]
newest = false
parts = dent
package = dent prefect beeblebox
extensions = gp.vcsdevelop
develop = .
eggs-directory = ${buildout:directory}/var/eggs
develop-eggs-directory = ${buildout:directory}/var/develop-eggs
parts-directory = ${buildout:directory}/var/parts
develop-dir = ${buildout:directory}/var/develop
bin-directory = ${buildout:directory}/bin
requirements = ${buildout:develop}/requirements.txt

[dent]
recipe = zc.recipe.egg
eggs = ${buildout:requirements-eggs}
        dent
        prefect
        beeblebox
```

Control the output
------------------

If you want to only generate the `buildout.cfg` file, simply use buildstrap with
no subcommand, and you'll get it in your current directory!

```
% buildstrap slartibartfast requirements.txt
% cat buildout.cfg
[buildout]
newest = false
parts = slartibartfast
package = slartibartfast
extensions = gp.vcsdevelop
develop = .
eggs-directory = ${buildout:directory}/var/eggs
develop-eggs-directory = ${buildout:directory}/var/develop-eggs
parts-directory = ${buildout:directory}/var/parts
develop-dir = ${buildout:directory}/var/develop
bin-directory = ${buildout:directory}/bin
requirements = ${buildout:develop}/requirements.txt

[slartibartfast]
recipe = zc.recipe.egg
eggs = ${buildout:requirements-eggs}
        slartibartfast

```

but if you want to just test the command and print the configuration to stdout,
without it doing nothing, use the `show` subcommand:

```
% buildstrap show slartibartfast requirements.txt
[buildout]
newest = false
parts = slartibartfast
package = slartibartfast
extensions = gp.vcsdevelop
develop = .
eggs-directory = ${buildout:directory}/var/eggs
develop-eggs-directory = ${buildout:directory}/var/develop-eggs
parts-directory = ${buildout:directory}/var/parts
develop-dir = ${buildout:directory}/var/develop
bin-directory = ${buildout:directory}/bin
requirements = ${buildout:develop}/requirements.txt

[slartibartfast]
recipe = zc.recipe.egg
eggs = ${buildout:requirements-eggs}
        slartibartfast

```

and if you want to write the `buildout.cfg` as another file, you can either redirect
the show command with a pipe, or use the `--output` argument:

```
% buildstrap -o foobar.cfg slartibartfast requirements.txt
% cat foobar.cfg
[buildout]
newest = false
parts = slartibartfast
package = slartibartfast
extensions = gp.vcsdevelop
develop = .
eggs-directory = ${buildout:directory}/var/eggs
develop-eggs-directory = ${buildout:directory}/var/develop-eggs
parts-directory = ${buildout:directory}/var/parts
develop-dir = ${buildout:directory}/var/develop
bin-directory = ${buildout:directory}/bin
requirements = ${buildout:develop}/requirements.txt

[slartibartfast]
recipe = zc.recipe.egg
eggs = ${buildout:requirements-eggs}
        slartibartfast

```

N.B.: the show command is equivalent to `--output -`.

# Configure the path

For your project, there are three important path to configure:

* where your project root is,
* where your sources are (within your project),
* where your environment will be.

When you're using buildstrap on a project, the default are safe, as long as you're
running while you're doing it within the sources of the project. Then what you'll have
is:

* `root_path` → '.'
* `src_path` → `{root_path}` → '.'
* `env_path` → `{root_path}/var` → './var'
* `bin_path` → `{root_path}/bin` → './bin'

But sometimes, you want to change the defaults, for the best (or the worst
— most often, the worst, though).

So, you can set all those paths to values other than the default, and have it
all in a very different setup than the default.

## Root path: `--root`

The project's root is where typically all other paths are being relative to.
It's where you'll expect to find the `buildout.cfg` file, and where the
environment directory will be.

When passed, it's setting up the `directory` directive of the `buildout.cfg`
file, otherwise it's keeping the default.

```
% buildstrap -r /tmp/buildstrap-env/ show buildstrap requirements.txt
[buildout]
newest = false
parts = buildstrap
package = buildstrap
extensions = gp.vcsdevelop
directory = /tmp/buildstrap-env/
develop = .
eggs-directory = ${buildout:directory}/var/eggs
develop-eggs-directory = ${buildout:directory}/var/develop-eggs
parts-directory = ${buildout:directory}/var/parts
develop-dir = ${buildout:directory}/var/develop
bin-directory = ${buildout:directory}/bin
requirements = ${buildout:develop}/requirements.txt

[buildstrap]
recipe = zc.recipe.egg
eggs = ${buildout:requirements-eggs}
        buildstrap
```

## Sources path: `--src`

Though, if you change the root directory, chances are (like in the former example) that
it won't be where your sources are. Then, running `buildout` will end up in throwing an
exception:

    FileNotFoundError: [Errno 2] No such file or directory: '/tmp/builstrap-env/./setup.py'

The source path is where you'll have your `setup.py` file that defines your project.
So, if your `setup.py` is not at the root of your project, you definitely want to
use the `--src` argument.

```
% buildstrap -r /tmp/buildstrap-build -s `pwd`/buildstrap show buildstrap requirements.txt
[buildout]
newest = false
parts = buildstrap
package = buildstrap
extensions = gp.vcsdevelop
directory = /tmp
develop = /absolute/path/to/buildstrap
eggs-directory = ${buildout:directory}/var/eggs
develop-eggs-directory = ${buildout:directory}/var/develop-eggs
parts-directory = ${buildout:directory}/var/parts
develop-dir = ${buildout:directory}/var/develop
bin-directory = ${buildout:directory}/bin
requirements = ${buildout:develop}/requirements.txt

[buildstrap]
recipe = zc.recipe.egg
eggs = ${buildout:requirements-eggs}
        buildstrap

```

*Nota Bene*: if you do not want to use a path relative to the `root` path, then
use an absolute path, or you'll have surprises! As you can see in the example above
the path is made absolute by using the `pwd` command.

So running this command with buildout will do:

```
% buildout
Creating directory '/tmp/buildstrap-build/var/eggs'.
Getting distribution for 'gp.vcsdevelop'.
warning: no previously-included files matching '*' found under directory 'docs/_build'
Got gp.vcsdevelop 2.2.3.
Creating directory '/tmp/buildstrap-build/bin'.
Creating directory '/tmp/buildstrap-build/var/parts'.
Creating directory '/tmp/buildstrap-build/var/develop-eggs'.
Develop: '/home/guyzmo/Workspace/Projects/buildstrap'
Getting distribution for 'zc.recipe.egg>=2.0.0a3'.
Got zc.recipe.egg 2.0.3.
Unused options for buildout: 'package'.
Installing buildstrap.
Generated script '/tmp/buildstrap-build/bin/buildout'.
Generated script '/tmp/buildstrap-build/bin/buildstrap'.
```

## Environment path: `--env`

As seen in the previous example, the script is generating a bunch of directories used
for setting up the environment in `{root_path}/var/`. You might want them to be named
differently, so they're not seen in listings for example:

```
% buildstrap -r /tmp -s `pwd`/buildstrap -e .var show buildstrap requirements.txt
[buildout]
newest = false
parts = buildstrap
package = buildstrap
extensions = gp.vcsdevelop
directory = /tmp
develop = /home/guyzmo/Workspace/Projects/buildstrap/buildstrap
eggs-directory = ${buildout:directory}/.var/eggs
develop-eggs-directory = ${buildout:directory}/.var/develop-eggs
parts-directory = ${buildout:directory}/.var/parts
develop-dir = ${buildout:directory}/.var/develop
bin-directory = ${buildout:directory}/bin
requirements = ${buildout:develop}/requirements.txt

[buildstrap]
recipe = zc.recipe.egg
eggs = ${buildout:requirements-eggs}
        buildstrap

```

or you might want to put it at any other place, by using an absolute path:

```
% buildstrap -r /tmp -s `pwd`/buildstrap -e /tmp/buildstrap-var show buildstrap requirements.txt
[buildout]
directory = /tmp
develop = /home/guyzmo/Workspace/Projects/buildstrap/buildstrap
eggs-directory = /tmp/buildstrap-var/eggs
develop-eggs-directory = /tmp/buildstrap-var/develop-eggs
parts-directory = /tmp/buildstrap-var/parts
develop-dir = /tmp/buildstrap-var/develop
bin-directory = ${buildout:directory}/bin
…
```

## Bin path: `--bin`

Finally, you might not like the default of having the `bin` directory at the
`root` path position, so you can put it within var the following way:

```
% buildstrap -b var/bin show buildstrap requirements.txt
[buildout]
develop = .
eggs-directory = ${buildout:directory}/var/eggs
develop-eggs-directory = ${buildout:directory}/var/develop-eggs
parts-directory = ${buildout:directory}/var/parts
develop-dir = ${buildout:directory}/var/develop
bin-directory = ${buildout:directory}/var/bin
…
```

or same as before, to somewhere other place non relative to the sources:

```
% buildstrap -r /tmp -s `pwd`/buildstrap -e /tmp/buildstrap-var -b /tmp/buildstrap-bin show buildstrap requirements.txt
[buildout]
develop = .
directory = /tmp/buildstrap-env/
eggs-directory = /tmp/buildstrap-var/eggs
develop-eggs-directory = /tmp/buildstrap-var/develop-eggs
parts-directory = /tmp/buildstrap-var/parts
develop-dir = /tmp/buildstrap-var/develop
bin-directory = /tmp/buildstrap-bin
…
```