bake-toolkit 2.11.2 → 2.11.3

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

@@ -0,0 +1,34 @@
+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: 50 %
+
+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

@@ -0,0 +1,11 @@
+Concepts
+==========
+
+.. toctree::
+    :maxdepth: 2
+
+
+    the_project_meta_file
+    the_main_project
+    build_hierarchy
+

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

@@ -0,0 +1,45 @@
+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

@@ -0,0 +1,72 @@
+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.
+

data/documentation/_build/html/_sources/ide/eclipse/eclipse.txt

@@ -0,0 +1,24 @@
+Eclipse
+=======
+
+.. toctree::
+    :maxdepth: 1
+
+    how_to_install_eclipse_plugin
+    how_to_use_bake_in_eclipse
+    how_to_convert_existing_cdt_workspace
+    how_to_create_a_workspace_in_eclipse
+    how_to_create_a_new_project_in_eclipse
+
+Syntax highlighting
+*******************
+
+To enable syntax highlighting for the Project.meta files in Eclipse, install the "rtext_eclipse_plugin" (Help->Install New Software...) and associate ".meta" files with the rtext editor (Window->Preferences, File Associations page).
+An update site for Eclipse (needed for installation) will be provided soon. For now, you can download it manually at github.
+
+Key bindings
+************
+
+It is possible to bind the bake commands to keys:
+
+.. image:: ../../_static/keys.png

data/documentation/_build/html/_sources/ide/eclipse/how_to_convert_existing_cdt_workspace.txt

@@ -0,0 +1,31 @@
+How to convert existing CDT workspaces
+======================================
+You only need to convert your workspace if CDT is still used to build your projects and the `Project.meta` files do not exist yet.
+Only one developer in a team has to convert the workspace only once!
+Conversion means, that Project.meta files are generated and filled with the informationen from the `.project` and `.cproject` 
+files. bake does not read the `.project` and `.cproject` files, only the `Project.meta` files.
+
+The converter is an export wizard, which can be found under `File->Export` or in the context menu of the Project Explorer
+
+=========================================           =======================================
+.. image:: ../../_static/SelectExport.png           .. image:: ../../_static/Script.png
+=========================================           =======================================
+
+.. note::
+
+    * The conversion is not a 1:1 conversion. That means, that the tool can only be 99% perfect. There might by some small issues, which have to be adapted manually. You can find it out by simply trying to build your project with bake.
+
+    * It is possible to specify a ruby script in the wizard window, which can do these manual adaptions. This can make sense, if you want to convert the workspace several times before completely switching to bake.
+
+    * To convert only a subset of projects instead of the whole workspace, select the appropriate projects in the Project Explorer before starting the export wizard. Ensure that the checkbox shown above is marked.
+
+    * If you are satisfied with the results, replace the .cproject and .project files in your repository. (Steps to do with .cproject and .project files)
+        * Delete the files
+        * Remove the projects from your workspace in Eclipse (but do not delete the contents from your disk)
+        * Import the projects again via the bake import wizard to generate wrapper files for Eclipse
+        * Commit the change to your source control system
+                   
+.. warning:: 
+    Do not commit these `.projec`t and `.cproject` files anymore. Instead, commit the changes in `Project.meta` files.
+    You still need `.cproject` and `.project` files for working under Eclipse, 
+    that's why you have to import the projects again via the bake import wizard.

data/documentation/_build/html/_sources/ide/eclipse/how_to_create_a_new_project_in_eclipse.txt

@@ -0,0 +1,18 @@
+How to create a new project in Eclipse
+======================================
+This is very easy. Navigate to `File->New->Other` and choose bake Project.
+
+=========================================           =======================================
+.. image:: ../../_static/SelectNew.png              .. image:: ../../_static/New.png
+=========================================           =======================================
+
+Choose a name. If you have more than one workspace root, you can also choose a location.
+
+ 
+
+=========================================           ===========================================================================
+.. image:: ../../_static/Result.png                 A new folder with three files will be created. `.cproject` and `.project`
+                                                    wrapper files for Eclipse and an almost. 
+                                                    empty `Project.meta` which can be filled with build configurations.
+=========================================           ===========================================================================
+

data/documentation/_build/html/_sources/ide/eclipse/how_to_create_a_workspace_in_eclipse.txt

@@ -0,0 +1,27 @@
+How to create a workspace in Eclipse
+====================================
+
+Using bake in Eclipse is very similar compared to the :any:`CDT build mechanism <how_to_convert_existing_cdt_workspace>`. 
+
+.. warning::
+    One major difference is, that `.cproject` and `.project` files are just wrappers. Do not use the standard property pages, 
+    they will be simply ignored! Edit only the `Project.meta` files.
+    The `.cprojec`t and `.project` files shall not be committed to your source control.
+
+Import
+******
+
+If you have a workspace with no `.cproject` and `.project` files, but `Project.meta` files, you can import them to Eclipse. 
+You can also use the importer to import single projects. 
+The importer can be found unter `File->Import` or in the context menu of the Project Explorer.
+All (sub)directories with a `Project.meta` are listed here. Choose the projects to import and press Finish.
+
+=========================================           =======================================
+.. image:: ../../_static/SelectImport.png           .. image:: ../../_static/Import.png
+=========================================           =======================================
+
+.. note::
+    Note, that `.cproject` and `.project` files will not be overwritten per default. If e.g. a project is not a c-project, 
+    some bake features will not available. In this case, enable the recreate option. 
+    This is also a good idea, if you want to get rid of old configurations.
+

data/documentation/_build/html/_sources/ide/eclipse/how_to_install_eclipse_plugin.txt

@@ -0,0 +1,44 @@
+How to install bake Eclipse integration
+=======================================
+
+The bake Eclipse integration plugin is available on a E.S.R.Labs update site. Please follow the steps below to install the plugin.
+
+#. Go to "Help" -> "Install New Software"
+
+    .. image:: ../../_static/InstallNewSoftware.png
+        :width: 100 %
+        :scale: 50 %
+
+#. Setup the update site
+
+    `<http://www.esrlabs.com/eclipse-plugins/com.esrlabs.eclipse.bake.updatesite/>`_
+
+    .. image:: ../../_static/AddRepository.png
+        :width: 100 %
+        :scale: 50 %
+
+#. Select the bake Feature
+
+    .. image:: ../../_static/AvailableSoftware.png
+        :width: 100 %
+        :scale: 50 %
+
+
+#. Accept the license after reading it
+
+    .. image:: ../../_static/Licenses.png
+        :width: 100 %
+        :scale: 50 %
+
+#. Ignore the security warning - you can trust the software
+
+    .. image:: ../../_static/TrustMe.png
+        :width: 100 %
+        :scale: 50 %
+
+#. After successfull installation, restart Eclipse 
+   
+    .. image:: ../../_static/Restart.png
+        :width: 100 %
+        :scale: 50 %
+

data/documentation/_build/html/_sources/ide/eclipse/how_to_use_bake_in_eclipse.txt

@@ -0,0 +1,86 @@
+How to use bake in Eclipse
+==========================
+
+Choose the C/C++ perspective
+****************************
+
+The menu items described on this page only appear in the C/C++ perspective.
+
+Select a build configuration of the main project
+************************************************
+
+#. Right click on the main project and select a bake build configuration. 
+  
+    .. image:: ../../_static/FirstSelect.png
+        :width: 100 %
+        :scale: 50 %
+
+    .. note::
+
+        * That only configurations with a DefaultToolchain will be displayed.
+
+#. If no Project.meta or configuration with a DefaultToolchain exist, an error item will be displayed like this
+
+    .. image:: ../../_static/WrongSelect.png
+        :width: 100 %
+        :scale: 50 %
+
+#. The chosen config is marked with a filled circle before the config name.You can also see it directly in the project explorer
+
+    .. image:: ../../_static/SecondSelect.png
+        :width: 100 %
+        :scale: 50 %
+
+    .. note::
+
+        * This label decoration can be switched off and on via Window->Preferences->General->Appearance->Label Decoration
+
+Adjust includes and defines for CDT
+***********************************
+s you might have already seen, a new menu item for the main project is enabled now: Adjust includes and defines for CDT.
+All CDT features work out-of-the-box except those about the `#include` and `#define` statements e.g. auto-completion of includes. 
+To import the includes and defines into the CDT .cproject files, simply click on this menu item.
+
+Compiler internal includes and defines must be specified in InternalInclude and InternalDefine files. 
+See "Syntax" help page how to set the name of these files. Note, that the variables CPPPath, CPath, ASMPath, 
+ArchiverPath and LinkerPath can be used in these files.
+
+Adjusting can take between a few seconds and a minute depending on the size of the workspace and the number of 
+project settings which have to be written.
+
+Build/Clean Projects/Files
+**************************
+Now you can build or clean a project by clicking on the appropriate menu items.
+
+=========================================           =======================================
+Project                                             File
+=========================================           =======================================
+.. image:: ../../_static/buildMain.png              .. image:: ../../_static/buildFile.png
+=========================================           =======================================
+
+.. note::
+    * Build File always rebuilds the file
+
+Result
+******
+
+The result of the build will be shown in the Console and Problems View as usual
+
+.. image:: ../../_static/console.png
+    :width: 100 %
+    :scale: 50 %
+
+.. image:: ../../_static/problem.png
+    :width: 100 %
+    :scale: 50 %
+
+
+Preferences
+***********
+
+Via `Window->Preferences->bake` some settings can be changed and the bake command line can be extended
+
+.. image:: ../../_static/pref.png
+    :width: 100 %
+    :scale: 50 %
+

data/documentation/_build/html/_sources/ide/ide_integrations.txt

@@ -0,0 +1,8 @@
+IDE Support
+===========
+
+.. toctree::
+    :maxdepth: 2
+
+    eclipse/eclipse
+    vs/vs

data/documentation/_build/html/_sources/ide/vs/how_to_create_vs_projects.txt

@@ -0,0 +1,15 @@
+How to create VS-Projects using bake
+====================================
+
+bake projects are Makefile projects (NMake). When creating a new project, you can just create a new Makefile project and add a Project.meta.
+The recommended way is to use a script which comes with bake-toolkit:
+
+    .. image:: ../../_static/cvsp.png
+        :width: 100 %
+        :scale: 50 %
+
+Example:
+
+.. code-block:: console
+
+    C:\MyProj>  createVSProjects --version 2012 --rewrite_solution

data/documentation/_build/html/_sources/ide/vs/how_to_debug_in_vs.txt

@@ -0,0 +1,35 @@
+How to Debug in Visual Studio
+=============================
+
+Natively you can only debug the output from the Microsoft VC compiler with Visual Studio. There are some plugins available for e.g. debugging gcc output. Another option is to use the MSVC toolchain from bake, which is described on this help page.
+Add debug flags to the MSVC toolchain:
+
+
+.. code-block:: text
+
+    DefaultToolchain MSVC {
+
+        Compiler CPP {
+            Flags "-Zi"
+        }
+        Linker {
+            Flags "-Debug"
+        }
+    }
+                
+Start Visual Studio with e.g. a batch file shown below and choose the appropriate solution. If you don't have a solution yet, check out How to create a solution / projects in Visual Studio.
+
+.. code-block:: console
+
+    set PATH=%PATH%;C:\tools\Microsoft Visual Studio 11.0\VC\bin
+    call "C:\tools\Microsoft Visual Studio 11.0\VC\vcvarsall.bat"
+    "C:\tools\Microsoft Visual Studio 11.0\Common7\IDE\devenv.exe"
+
+This adds the compiler, linker, etc. to the path. vcvarsall.bat setups the environment and the last line starts Visual Studio. As a test, just execute the first two lines and check if "cl.exe" can be executed without any errors. In Visual Studio, you have to define the executable you like to debug. Add the executable in the project properties:
+
+.. image:: ../../_static/vs_debug.png
+    :width: 100 %
+    :scale: 50 %
+
+You can also define command line arguments here.
+Start debugging as usual...