Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/grisumbras/b2-helper

Conan build helper for projects that use Boost.Build
https://github.com/grisumbras/b2-helper

boost-build conan package-management

Last synced: 17 days ago
JSON representation

Conan build helper for projects that use Boost.Build

Awesome Lists containing this project

README 

        
= b2-helper

:toc: preamble



image:https://api.bintray.com/packages/grisumbras/conan/b2-helper%3Agrisumbras/images/download.svg[Download,link=https://bintray.com/grisumbras/conan/b2-helper%3Agrisumbras/_latestVersion]

image:https://github.com/grisumbras/b2-helper/workflows/Build/badge.svg?branch=master[Build status,link=https://github.com/grisumbras/b2-helper/actions]



____

https://conan.io[Conan] build helper for projects that use

https://boostorg.github.io/build[Boost.Build]

____



== Install



Add the necessary conan remote:



[source,shell]

----

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

----



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

package:



[source,python]

----

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:



[source,python]

----

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`:



[source,python]

----

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):



[source,python]

----

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.



[source,python]

----

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.



[source,python]

----

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 : "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 



== Contributing

Patches welcome!



== License

link:LICENSE[BSL-1.0] (C) 2018-2019 Dmitry Arkhipov