bake-toolkit 2.29.4 → 2.30.0

data/documentation/_build/html/_sources/commandline/commandline.txt

@@ -1,109 +0,0 @@
-Commandline
-===========
-
-How to get help
-***************
-
-.. code-block:: console
-
-    User@Host:~$ bake -h
-
-The most important options
-**************************
-
-#. *-b* the build configuration name
-
-#. *-m* the main project directory (default is current directory)
-
-#. *-p* the project to build (if not specified, the main project will be built with all dependencies)
-
-   .. note::
-
-        All configs of the project will be built, which is usually just one config, but if you have more than one config of the project in the workspace, use a comma separator.
-
-Examples
-********
-
-Building an application
------------------------
-
-    .. code-block:: console
-
-        User@Host:~$ bake -b Debug
-
-    .. note::
-
-        It is possible to omit *-b*:
-
-        .. code-block:: console
-
-            User@Host:~$ bake Debug
-
-Building from within an arbitrary directory
--------------------------------------------
-
-    .. code-block:: console
-
-        User@Host:~$ bake Debug -m w:/root/mainProj
-
-Building just one specific project
------------------------------------
-Assuming the project name to build s myProj.
-
-    .. code-block:: console
-
-        User@Host:~$ bake Debug -m w:/root1/myProj -p myProj
-
-Building specific projects with differnt roots
-----------------------------------------------
-Assuming mainProj has several configs really included in the build (which is uncommon), you can choose one of the configs.
-
-
-    .. code-block:: console
-
-        User@Host:~$ bake Debug -m w:/root1/myProj -p myProj,abc
-
-
-Building a project which has more than one root
------------------------------------------------
-Assuming code has been checked out into two roots, the console supports ansi colors, you want to stop on first error and build only the project bspAbc.
-
-    .. code-block:: console
-
-        User@Host:~$ bake Debug -m w:/root1/myProj -w w:/root1 -w w:/root2 -r -a black -p bspAbc
-
-
-Clean a project(s)
-------------------
-
-    .. code-block:: console
-
-        User@Host:~$ bake Debug -m w:/root1/myProj -w w:/root1 -w w:/root2 -r -a black -p bspAbc -c
-
-Build a single file(s)
-----------------------
-    .. code-block:: console
-
-        User@Host:~$ bake Debug -p bspAbc -f main.cpp
-        User@Host:~$ bake Debug -f .asm
-
-    .. note::
-
-        All files matching the pattern will be compiled (no wildcards allowed)
-
-
-roots.bake
-**********
-
-Workspace roots can be defined in a file called "roots.bake", which will be searched from main project directory to root folder.
-Example:
-
-    .. code-block:: console
-
-        ../..
-        C:/another/root # comments written like this
-        something/else
-
-If -w and roots.bake are specified, they will be merged. First -w, then roots.bake.
-
-If -w and roots.bake are not specified, the default workspace root is the parent directory of the main project.

data/documentation/_build/html/_sources/concepts/build_hierarchy.txt

@@ -1,34 +0,0 @@
-The build hierarchy
-===================
-
-Build graph
-***********
-
-Depending on the contents of the Project.meta files, a build graph will be generated:
-    * An ExecutableConfig usually specifies files to compile, dependencies to other projects and linker stuff.
-    * A LibraryConfig usually specifies files to compile and archive.
-    * A CustomConfig usually defines a custom step.
-
-Every config type can be equipped with pre and post steps like shell commands or makefiles.
-
-All these steps will be combined to a build graph.
-
-Example
-*******
-
-The main project has dependencies to the projects A, B and C:
-
-    .. image:: ../_static/bake_build_hierachy.png
-        :width: 100 %
-        :scale: 75 %
-
-Steps are executed bottom-up. If one step fails, all steps above won't be executed.
-
-If e.g.
-    * PreStepMain 2 fails
-    * at least one file of library B does not compile
-then
-    * library B will not be created
-    * files of the main project will not be compiled
-    * main project will not be linked
-    * post step of main project will not be executed

data/documentation/_build/html/_sources/concepts/concepts.txt

@@ -1,14 +0,0 @@
-Concepts
-==========
-
-.. toctree::
-    :maxdepth: 2
-
-
-    the_project_meta_file
-    the_main_project
-    build_hierarchy
-    link_order
-    prebuild
-    inject
-

data/documentation/_build/html/_sources/concepts/inject.txt

@@ -1,65 +0,0 @@
-Injection and inheritance of IncludeDir and Dependency
-******************************************************
-
-It is possible to inject and inherit "includes" and inject "dependencies".
-
-Inherit IncludeDir
-==================
-
-.. code-block:: console
-
-    IncludeDir include, inherit: true
-
-This is typically used to make include directories available to upper levels, e.g.:
-
-
-.. code-block:: console
-
-    # in MyLib/Project.meta
-    LibraryConfig Lib {
-      ...
-      IncludeDir include, inherit: true
-    }
-
-    # in main/Project.meta
-    ExecutableConfig Debug {
-      ...
-      Dependency MyLib, config: Lib
-      # IncludeDir "MyLib/include" - not needed because this IncludeDir is inherited
-    }
-
-Inject IncludeDir
-=================
-
-.. code-block:: console
-
-    IncludeDir "mock/include", inject: front
-
-"front" is used for mocking IncludeDirs, e.g. if a library shall include a mocked class instead of the original one in UnitTest context.
-
-.. code-block:: console
-
-    IncludeDir include, inject: back
-
-"back" is used if the lower levels do not know by themselves what to include. So this has to be configured from the outside, typically in the main project.
-
-Inject Dependency
-=================
-
-.. code-block:: console
-
-    Dependency MyLib, inject: front # or back
-
-This is used if a component cannot have this dependency hard coded, because it shall not know the concrete implementation or the dependency is only used for unittesting.
-
-Example:
-
-.. code-block:: console
-
-    ExecutableConfig UnitTest {
-      ...
-      Dependency config: Lib
-      Dependency googleTest, inject: front
-    }
-
-In this example the config Lib depends on googleTest. If googleTest inherits an IncludeDir, this would be known by Lib.

data/documentation/_build/html/_sources/concepts/link_order.txt

@@ -1,91 +0,0 @@
-The link order
-==============
-
-The link order depends on the order of library definitions and dependencies in the Project.meta files.
-
-In general, if a library X depends on a library Y, the library X must be linked before Y.
-
-Example:
-********
-
-.. code-block:: console
-
-    Project A:
-
-    Dependency B
-    Dependency C
-
-.. code-block:: console
-
-    Project B:
-
-    Dependency D
-
-.. code-block:: console
-
-    Project C:
-
-    Dependency D
-
-.. code-block:: console
-
-    Project D:
-
-The link order will be
-
-- Objects of A
-- B
-- C
-- D
-
-Same example but with external libraries:
-*****************************************
-
-.. code-block:: console
-
-    Project A:
-
-    ExternalLibrary a1
-    Dependency B
-    ExternalLibrary a2
-    Dependency C
-    ExternalLibrary a3
-
-.. code-block:: console
-
-    Project B:
-
-    ExternalLibrary b1
-    Dependency D
-    ExternalLibrary b2
-
-.. code-block:: console
-
-    Project C:
-
-    ExternalLibrary c1
-    Dependency D
-    ExternalLibrary c2
-
-.. code-block:: console
-
-    Project D:
-
-    ExternalLibrary d1
-    ExternalLibrary d2
-
-The link order will be
-
-- Objects of A
-- a1
-- B
-- b1
-- b2
-- a2
-- C
-- c1
-- D
-- d1
-- d2
-- c2
-- a3

data/documentation/_build/html/_sources/concepts/prebuild.txt

@@ -1,57 +0,0 @@
-Prebuild configurations for distributions
-*****************************************
-
-This is a useful feature if you want to make a part of workspace available for third party without changing the configuration.
-
-There are two major use cases:
-
-- Only a few projects shall be closed source (e.g. to hide some algorithms)
-- Only a few projects shall be open source (e.g. if a supplier has integrate a library)
-
-Both is possible with bake, but the current UI is optimized for the latter one.
-
-Add in the Project.meta the following code:
-
-.. code-block:: console
-
-    Prebuild {
-      Except main, config: Debug
-      Except newLib, config: Debug
-      Except setup, config: Release
-    }
-
-It is possible to specify the Prebuild tags in all configurations, not only in the main configuration. Logically they will be merged.
-
-In the example above, no configurations will be built - except those three. The prebuild output is used directly.
-
-To reference a configuration of the same project, omit the project name, e.g.:
-
-.. code-block:: console
-
-    Except config: Base
-
-To reference all configuration of a project, omit the config name, e.g.:
-
-.. code-block:: console
-
-    Except newLib
-
-
-This prebuild behaviour must be explicitly turned on by using the following the command line argument:
-
-.. code-block:: console
-
-    --prebuild
-
-Note, that if objects files exist, the library will be built from existing object files (glob for \*.o in appropriate build folder). If only the archive exists, the archive will be used without building it.
-
-Typical workflow
-----------------
-
-1. Compiling the workspace completely without prebuild feature.
-2. Executing a distribution script which copies all relevant files to a distribution directory.
-   Make sure to add all header files of prebuild libraries if they are needed for other non-prebuild libraries.
-   You may use the dependency files in the output directory for that script.
-3. In the distribution folder use "--prebuild" when compiling the workspace.
-
-

data/documentation/_build/html/_sources/concepts/the_main_project.txt

@@ -1,45 +0,0 @@
-The main project
-================
-The concept of the main project is different to many other build systems like Eclipse CDT.
-In these build systems everything which is needed for a project is configured in the project itself.
-In bake the main project can predefine stuff for all subprojects.
-The main project can have a DefaultToolchain definition, which is valid for all projects and files referenced by the main project. Subprojects can overwrite or adjust these definitions.
-
-Projects are always built in context of the main project.
-
-To build a project, you have to specify
-
-    * the main project
-    * the config of the main project which references the project to build
-    * the (sub)project to build if applicable
-
-Advantages
-**********
-
-Reducing the number of build configurations (toolchain settings like debug or release flags can be set outside of the project)
-Most projects do not have any compiler definitions anymore
-Only flags which must be used or flags which must not be used have to be specified in the projects
-Changing compiler definitions for all projects can be done easily in the main project build configuration
-
-Example
-*******
-
-==============================================   ==============================================
-Project.meta of Main (Debug and Release)         Project.meta of Sub (only one build config!)
-==============================================   ==============================================
-.. literalinclude:: ../_static/Main.meta         .. literalinclude:: ../_static/Lib.meta
-==============================================   ==============================================
-
-.. note::
-
-    A main project must have a DefaultToolchain - but it's allowed to leave that definition empty.
-
-Output directory
-****************
-
-A project in a specific build configuration can be build in different contexts.
-That's why the output directory of a project cannot be simply the build configuration name of the project to avoid inconsistencies.
-Therefore the output directory names are.
-
-    * Main project: $(MainConfigName) like in regular Eclipse CDT builds
-    * Subprojects: $(MainConfigName)_$(MainProjectName) instead of the config name of the subproject

data/documentation/_build/html/_sources/concepts/the_project_meta_file.txt

@@ -1,72 +0,0 @@
-The Project.meta file
-=====================
-
-What is the Project.meta file
-*****************************
-The `Project.meta` file is bakes configuration file.
-
-* Every project has a Project.meta file in the project root directory.
-* A Project.meta file contains one or more build configurations.
-* A build configuration consists of toolchain settings, files to build, custom steps, etc.
-
-Example
-*******
-
-=============================================         =============================================
-Project.meta file of Main project                     Project.meta file of Sub project
-=============================================         =============================================
-.. literalinclude:: ../_static/PMetaMain.meta         .. literalinclude:: ../_static/PMetaSub.meta
-=============================================         =============================================
-
-Let's assume that Main and Sub are located in the same workspace root.
-To build the executable, bake can be called from the Main directory.
-
-    .. code-block:: console
-
-        User@Host:~/my_project$ bake -b Debug
-
-What happens now?
-
-    #. Reading Project.meta of Main
-    #. Reading Project.meta of dependencies (Sub)
-    #. Compiling sources of Sub, e.g.:
-        .. code-block:: console
-
-            User@Host:~$ g++ -c -Wall -g3 -Iinclude -I../Main/include -o Debug_Main/src/xy.o src/xy.cpp
-
-        * Wall is taken from the DefaultToolchain and -g3 is added by the toolchain of the Sub project.
-
-        * The include path to Main is automatically adjusted.
-
-        * The order of includes is the same as in Project.meta.
-
-        * g++, -c and -I are used, because GCC was specified in the DefaultToolchain.
-
-    #. Archiving the library, e.g.:
-
-        .. code-block:: console
-
-            User@Host:~$ ar -rc Debug_Main/libSub.a Debug_Main/src/xy.o
-
-    #. Compiling sources of Main, e.g.:
-
-        .. code-block:: console
-
-            User@Host:~$ g++ -c -Wall -Iinclude -o Debug/src/main.o src/main.cpp
-
-    #. Linking executable, e.g.:
-
-        .. code-block:: console
-
-            User@Host:~$ g++ -o Debug/Main.exe Debug/src/main.o ../Sub/Debug_Main/libSub.a -L../Sub/lib -la -lb
-
-        The library search paths and libraries are added in the specified order.
-
-    #. Executing the post step
-
-        .. code-block:: console
-
-            User@Host:~$ echo Main.exe built.
-
-        The variable was automatically substituted.
-