diff options
Diffstat (limited to 'doc/source/examples/out-of-source-build.rst')
-rw-r--r-- | doc/source/examples/out-of-source-build.rst | 173 |
1 files changed, 173 insertions, 0 deletions
diff --git a/doc/source/examples/out-of-source-build.rst b/doc/source/examples/out-of-source-build.rst new file mode 100644 index 000000000..b8573398a --- /dev/null +++ b/doc/source/examples/out-of-source-build.rst @@ -0,0 +1,173 @@ + +.. _examples_out-of-source-build.rst: + +Building out of source +====================== + +Intro +----- + +This example aims to: + + * Give a basic overview of how out of source builds work. This is done by + collecting the relevant bits of information spread across different sections + of the documentation that tend to group information by element rather than + task. + * Give Examples of how to use out of source builds. + +Buildstream aims to make out of source builds easy and consistent across as +many build systems as possible. However it should be noted that not all build +systems support `out of source builds`. + +Key Variables +------------- + +Out of source builds are configured by setting: + + * ``directory`` of the source, this sets the source to extract to a folder in + the build root. + * ``command-subdir`` variable, sets the directory were the build commands + will be run. + * ``conf-root`` variable, tells the configuration tool were to find the root of + the source code. + +``conf-root`` is given to the configuration tool which is run in +``command-subdir``. It can either be given as a relative path from +``command-subdir`` to the location of the source code. Or as an absolute +location. + +By setting ``conf-root`` as a absolute path we can change ``command-subdir`` +with out having to change ``conf-root``. + +If a absolute path is given it must be from the root of the sandbox. +To specify a absolute path from the root of the build-root the build-root +variable can be used eg. ``conf-root`` can be set to ``"%{build-root}/Source"`` +to specify the ``Source`` folder in the root of the build-root. + +These variables can be use for many of the buildstream build element kinds. +Indeed converting to out of source builds should be as simple as adding these +variables to the individual bst files and in some circumstance most of the +variables could be set at a project level. + + +Examples +-------- + +The out of source examples can be found in the buildstream source code in +``doc/examples/out-of-source`` folder in the buildstream source. The two cmake +elements we will use as examples are `sourceroot.bst` and `subfolder.bst`. + +It is very simple to create a build element that loads a source in to the +`build-root` and then uses the standard build tools to build the project in the +same folder. Buildstream has lots of build element plugs so that a new element +may only need to set its `kind` to the relevant build system and then define a +source, the `sourceroot.bst` example element takes a cmake exmaple and expands +it to a out of source build. + +An alternative build elements might build in a sub folder of the source. The +`hello.bst` element in the `autotools` example dose this. And a out of source +version is given in the `subfolder.bst` element of the out of source example +project. + + +Build project defined in source root +------------------------------------ + +This example points cmake at the root of the source. + +In this example, the CMakeLis.txt in the root folder of the source +causes the helloworld program to state that it was build from the root of the +source project when called. + +To make the software build in a folder outside of the source code we set the +source to be in a sub folder of the build-root folder rather than in its root, +in our case this folder will be called ``source``. + +The build tools are then set to run a separate folder in the build-root folder, +this will be called ``build``. We must then tell the build tools were to +find the source code, this is done with the ``conf-root`` variable. + +This is done by: + + * Setting the sources ``directory`` property to ``Source`` + * Setting the element variable ``command-subdir`` to ``build`` + * Setting the element variable ``conf-root`` to ``"%{build-root}/Source"`` + + +``sourceroot.bst`` +~~~~~~~~~~~~~~~~~~ + +.. literalinclude:: ../../examples/out-of-source-build/elements/sourceroot.bst + :language: yaml + +We can then use the ``bst show`` command to see how variable like ``conf-root`` +are expanded. + +.. raw:: html + :file: ../sessions/out-of-source-build-show-variables.html + + +Using a workspace or a shell with `--build` can be used to see the folder +structure that gets created. When bst shell is launched it runs in the +``command-subdir`` directory. If ``ls ..`` is run we can see that the build-root +now contains the ``build`` folder and the ``Source`` folder. + +.. raw:: html + :file: ../sessions//out-of-source-build-shell-ls.html + + + +Build project defined in source subdirectory +-------------------------------------------- + +This example points cmake at he `main` directory inside the source. + +In this example, the CMakeLis.txt in the folder main in the root of the +source causes the helloworld program to state that it was build from a subfolder +of the source project when called. + +To make the software build in a folder outside of the source code we set the +source to be in a sub folder of the build-root folder rather than in its root, +in our case this folder will be called ``source``. + +The build tools are then set to run a separate folder in the build-root folder, +this will be called ``build``. We must then tell the build tools were to +find the source code, this is done with the ``conf-root`` variable. +Unlike the previous example we need ``conf-root`` to point the sub directory of +the source project rather than the root. + + + +This is done by: + + * Setting the sources ``directory`` property to ``Source`` + * Setting the element variable ``command-subdir`` to ``build`` + * Setting the element variable ``conf-root`` to + ``"%{build-root}/Source/main"`` + +``subfolder.bst`` +~~~~~~~~~~~~~~~~~ + +.. literalinclude:: ../../examples/out-of-source-build/elements/subfolder.bst + :language: yaml + + +Run the hello world program +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We can see the output of the two different binaries created from the same +source by invoking the shell of the respective elements with the new programs +name. + +When the binary from the build that included the file that defined the extra build +flag ``FULL_PROJECT`` is run, we get the following output: + +.. raw:: html + :file: ../sessions/out-of-source-build-shell.html + +When the binary from the build that pointed to the CMakeList.txt that +just adds the source without defining any extra build flags is run, we get the +following output: + +.. raw:: html + :file: ../sessions/out-of-source-build-shell-subfolder.html |