README.adoc

b2-helper

Conan build helper for projects that use Boost.Build

Table of Contents

• Install
• Usage
  • Using mixin
  • Using helper
  • Using with pre-generated project-config.jam
• API
  • class B2
  • class B2.Mixin
  • class OptionsProxy
  • class PropertySet
• Maintainer
• Contributing
• License

Install

Add the necessary conan remote:

$ conan remote add grisumbras https://api.bintray.com/conan/grisumbras/conan

Inside your conanfile.py use python_requires to install and import the package:

class MyConan(ConanFile):
    python_requires = "b2-helper/[>=0.8.0]@grisumbras/stable"

Usage

Using mixin

The simplest way to use the package is via the mixin class:

class MyConan(ConanFile):
    python_requires = "b2-helper/[>=0.8.0]@grisumbras/stable"
    python_requires_extend = "b2-helper.Mixin"

The mixin provides default implementations for methods build, package and test. In order for it to work without any customization, project’s jamroot file should be in conanfile.source_folder and the project should require no configuration beyond toolset initialization. If customization is required, the ConanFile subclass should override method b2_setup_builder:

class MyConan(ConanFile):
    python_requires_extend = "b2-helper.Mixin"

    def b2_setup_builder(self, builder):
        builder.source_folder = "src"
        builder.build_folder = "build"
        builder.options.debug_building = True
        builder.properties.runtime_link = "static"
        return builder

If you need to build specific targets, you can sepcify them via b2_build_targets. The value of the variable can be any collection or string (in case you want to only build one target):

class MyConan1(ConanFile):
    python_requires_extend = "b2-helper.Mixin"
    b2_build_targets = "foo"

class MyConan2(ConanFile):
    python_requires_extend = "b2-helper.Mixin"
    b2_build_targets = "foo", "bar"

Using helper

The helper can be used by itself pretty much the same way as standard build helpers.

class MyConan(ConanFile):
    def build(self):
        builder = b2.B2(self)
        builder.source_folder = "src"
        builder.build_folder = "build"
        builder.options.debug_building = True
        builder.properties.runtime_link = "static"
        builder.configure()
        builder.build()
        builder.test()
        builder.install()

Using with pre-generated project-config.jam

By default the helper creates a project-config.jam which initializes modules and loads files created by generator. Some projects prefer to create that file themselves via a bootstrap script. In order to support such use cases the helper provides mutable property project_config and an attribute include that holds a list of jamfiles to be included by configuration module.

class MyConan(ConanFile):
    def b2_setup_builder(self, builder)
        builder.project_config = os.path.join(self.build_folder, "helper.jam")
        builder.include.append(self.bootstrap())
        return builder

API

class B2

Methods

• def init(self, conanfile, no_defaults=False) Constructor. If no_defaults == True, does not fill default property set with default properties.

• def using(self, name, *args, **kw) Initializes a toolset module. self.using(("a", "b"), "c", {"d": "e"}) is equivalent to putting using a : b : c : <d>"e" ; in Boost.Build configuration.

• def configure(self) Creates project configuration file in self.project_config.

• def build(self, *targets) Builds targets targets. If no targets were specified, builds default targets, but only if conanfile.should_build == True.

• def install(self, force=False) Builds target install if conanfile.should_install == True or if force == True.

• def test(self, force=False) Builds target test if conanfile.should_test == True and if environment variable CONAN_RUN_TESTS is either not defined or is equals True, or if force == True.

Attributes

• source_folder path to folder that contains jamroot file.

• build_folder path to folder that will contain build artifacts.

• package_folder path to folder that will contain install artifacts.

• project_config path to created project configuration file.

• executable Boost.Build executable that will be used.

• properties property set that will be used in build request.

• options a collection of CLI options.

class B2.Mixin

TBD

class OptionsProxy

TBD

class PropertySet

TBD

Maintainer

Dmitry Arkhipov <[email protected]>

Contributing

Patches welcome!

License

BSL-1.0 © 2018-2019 Dmitry Arkhipov