### No-Install Quickstart

There is no need to “install Boost” in order to get started using Boost.Python. These instructions use Boost.Build projects, which will build those binaries as soon as they're needed. Your first tests may take a little longer while you wait for Boost.Python to build, but doing things this way will save you from worrying about build intricacies like which library binaries to use for a specific compiler configuration and figuring out the right compiler options to use yourself.

| Note

Of course it's possible to use other build systems to build Boost.Python and its extensions, but they are not officially supported by Boost. Moreover 99% of all “I can't build Boost.Python” problems come from trying to use another build system without first following these instructions.

If you want to use another system anyway, we suggest that you follow these instructions, and then invoke `bjam` with the

`-a -o`filename

options to dump the build commands it executes to a file, so you can see what your alternate build system needs to do.

#### Basic Procedure

1. Get Boost; see sections 1 and 2 of the Boost Getting Started Guide.

2. Get the `bjam` build driver. See section 5 of the Boost Getting Started Guide.

3. cd into the `example/quickstart/` directory of your Boost.Python installation, which contains a small example project.

4. Invoke `bjam`. Replace the “`stage`“ argument from the example invocation from section 5 of the Boost Getting Started Guide with “`test`,“ to build all the test targets. Also add the argument “`--verbose-test`” to see the output generated by the tests when they are run. On Windows, your `bjam` invocation might look something like:

    C:\\...\\quickstart> bjam toolset=msvc --verbose-test test

and on Unix variants, perhaps,

    .../quickstart$ bjam toolset=gcc --verbose-test test

| Note
For the sake of concision, the rest of this guide will use unix-style forward slashes in pathnames instead of the backslashes with which Windows users may be more familiar. The forward slashes should work everywhere except in Command Prompt windows, where you should use backslashes.

If you followed this procedure successfully, you will have built an extension module called `extending` and tested it by running a Python script called `test_extending.py`. You will also have built and run a simple application called `embedding` that embeds python.

#### In Case of Trouble

If you're seeing lots of compiler and/or linker error messages, it's probably because Boost.Build is having trouble finding your Python installation. You might want to pass the `--debug-configuration` option to `bjam` the first few times you invoke it, to make sure that Boost.Build is correctly locating all the parts of your Python installation. If it isn't, consider Configuring Boost.Build as detailed below.

If you're still having trouble, Someone on one of the following mailing lists may be able to help:

- The Boost.Build mailing list for issues related to Boost.Build
- The Boost.Python mailing list for issues specifically related to Boost.Python

#### In Case Everything Seemed to Work

Rejoice! If you're new to Boost.Python, at this point it might be a good idea to ignore build issues for a while and concentrate on learning the library by going through the Tutorial and perhaps some of the Reference Manual, trying out what you've learned about the API by modifying the quickstart project.

#### Modifying the Example Project

If you're content to keep your extension module forever in one source file called `extending.cpp`, inside your Boost.Python distribution, and import it forever as `extending`, then you can stop here. However, it's likely that you will want to make a few changes. There are a few things you can do without having to learn Boost.Build in depth.

The project you just built is specified in two files in the current directory: `boost-build.jam`, which tells `bjam` where it can find the interpreted code of the Boost build system, and `Jamroot`, which describes the targets you just built. These files are heavily commented, so they should be easy to modify. Take care, however, to preserve whitespace. Punctuation such as `;` will not be recognized as intended by `bjam` if it is not surrounded by whitespace.

##### Relocate the Project

You'll probably want to copy this project elsewhere so you can change it without modifying your Boost distribution. To do that, simply

a. copy the entire `example/quickstart/` directory into a new directory.

b. In the new copies of `boost-build.jam` and `Jamroot`, locate the relative path near the top of the file that is clearly marked by a comment, and edit that path so that it refers to the same directory your Boost distribution as it referred to when the file was in its original location in the `example/quickstart/` directory.

For example, if you moved the project from `/home/dave/boost_1_34_0/libs/python/example/quickstart` to `/home/dave/my-project`, you could change the first path in `boost-build.jam` from

    ../../../../tools/build/src

to

    /home/dave/boost_1_34_0/tools/build/src

and change the first path in `Jamroot` from

    ../../../..

to

    /home/dave/boost_1_34_0

##### Add New or Change Names of Existing Source Files

The names of additional source files involved in building your extension module or embedding application can be listed in `Jamroot` right alongside `extending.cpp` or `embedding.cpp` respectively. Just be sure to leave whitespace around each filename:

    … file1.cpp file2.cpp file3.cpp …

Naturally, if you want to change the name of a source file you can tell Boost.Build about it by editing the name in `Jamroot`.

##### Change the Name of your Extension Module

The name of the extension module is determined by two things:

1. the name in `Jamroot` immediately following `python-extension`, and
2. the name passed to `BOOST_PYTHON_MODULE` in `extending.cpp`.

To change the name of the extension module from `extending` to `hello`, you'd edit `Jamroot`, changing

    python-extension extending : extending.cpp ;

to

    python-extension hello : extending.cpp ;

and you'd edit extending.cpp, changing

    BOOST_PYTHON_MODULE(extending)

to

    BOOST_PYTHON_MODULE(hello)