bake-toolkit 2.11.2 → 2.11.3

data/documentation/_build/html/_sources/syntax/derive_configs.txt

@@ -0,0 +1,93 @@
+Derive configs
+==============
+
+bake supports deriving configs, which allows you to put repetetive settings in a base config.
+
+Deriving a config
+*****************
+
+Derving a config in bake is pretty straight forward, and looks like this:
+
+.. code-block:: text
+
+    ExecutableConfig A
+    LibraryConfig    B, extends: A
+    CustomConfig     C, extends: B
+    ExecutableConfig D, extends: C
+
+.. note::
+
+    The config type of the parent config does not matter, but only settings which are valid in BOTH configs will be inherited.
+    In the example above D gets the dependencies from A, because "Dependency" is valid in all configs, but D does not get 
+    the "Files" from A, because "Files" is not valid in CustomConfig.
+
+
+Inheritance implications
+************************
+
+============================        =========================================
+Setting                             Derived
+============================        =========================================
+Set                                 parent + child
+
+Dependency                          parent + child
+
+ExternalLibrary                     parent + child
+                                    (ordered by line number)
+
+ExternalLibrarySearchPath           parent + child
+                                    (ordered by line number)
+
+UserLibrary                         parent + child
+                                    (ordered by line number)
+
+PreSteps                            parent + child
+
+PostSteps                           parent + child
+
+Makefile                            used from parent if not 
+                                    in child
+
+CommandLine                         used from parent if not
+                                    in child 
+
+Files                               parent + child
+
+ExcludeFiles                        parent + child
+
+IncludeDir                          parent + child
+
+LinkerScript                        used from parent if not in child
+
+ArtifactName                        used from parent if not in child
+
+MapFile                             used from parent if not in child
+============================        =========================================
+
+
+============================        =========================================
+Toolchain Setting                   Derived
+============================        =========================================
+basedOn                             used from parent if not in child
+
+outputDir                           used from parent if not in child
+
+command                             used from parent if not in child
+
+LibPrefixFlags                      parent + child
+
+LibPostfixFlags                     parent + child
+
+Flags                               parent + child
+
+Define                              parent + child
+
+InternalDefines                     used from parent if not in child
+
+InternalIncludes                    used from parent if not in child
+
+LintPolicy                          parent + child
+
+Docu                                used from parent if not in child
+============================        =========================================
+

data/documentation/_build/html/_sources/syntax/project_meta_syntax.txt

@@ -0,0 +1,19 @@
+The Syntax of the Project.meta file
+===================================
+
+Instructions for the Interactive Syntax Viewer
+**********************************************
+
+* Move the mouse cursor over the blue elements to display more information.
+
+* Three config types exist: ExecutableConfig, LibraryConfig and CustomConfig. Move the mouse cursor over these elements to display the supported content.
+
+.. raw:: html
+    :file: ../_static/syntax.html
+
+.. note::
+    Specify the paths always relative to the current project root, but keep the variable substitution in Project.meta in mind.
+    
+    * Use double quotes (") if the strings have spaces or slashes.
+
+    * Use hash marks (#) for comments.

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

@@ -0,0 +1,10 @@
+Syntax
+==========
+
+.. toctree::
+    :maxdepth: 2
+
+    project_meta_syntax
+    variable_substitutions
+    derive_configs
+

data/documentation/_build/html/_sources/syntax/variable_substitutions.txt

@@ -0,0 +1,175 @@
+Variables in Project.meta
+=========================
+bake allows you to use pre defined and/or user defined variables in your Project.meta file.
+Defined variables then can be used using the following syntax:
+
+.. code-block:: console
+    
+   $(MyIncludes)
+
+The variable MyIncludes will be substitued by its value, therefore a real life usage would look
+something like this:
+
+.. code-block:: console
+    
+   IncludeDir "$(MyIncludes)"
+
+User defined variables
+**********************
+
+There are two ways to create user defined variables.
+
+#. The variable is defined with the `--set` command line option:
+
+.. code-block:: console
+ 
+    User@Host:~$ bake ... --set MyVar="Hello world!"
+
+#. THe variable is defined directly in the Project.meta file.
+
+.. code-block:: console
+
+    Set MyVar, value: "Hello world!"              
+
+
+Pre defined bake environment variables 
+**************************************
+
+========================================    ===============================================     ========================================
+Variable                                    Description                                         Example
+========================================    ===============================================     ========================================
+*$(MainConfigName)*                         Evaluates to the main config name                   Debug
+
+*$(MainProjectName)*                        Evaluates to the main project name                  bootloader
+
+*$(ConfigName)*                             Evaluates to the config name                        lib
+
+*$(ProjectName)*                            Evaluates to the project name                       canDriver
+
+*$(ProjectDir)*                             Evaluates to the full path of the project           C:/Root/MyProject
+                                            directory
+
+*$(MainProjectDir)*                         Evaluates to the full path of the root projec       C:/Root/Main
+                                            directory                                           
+
+*$(OutputDir)*                              Evaluates to the full path of the output            build_lib_bootloader_Debug
+                                            directory of the current config
+
+*$(OutputDir,projName,confName)*            Evaluates to the output dir of a specific           build_lib_some_Debug
+                                            config
+
+*$(ArtifactName)*                           Evaluates to the artifact.                          bootloader_1.0.elf
+
+*$(ArtifactNameBase)*                       Evaluates to the base artifact name                 bootloader_1.0
+                                            (Without file exension)
+
+*$(Time)*                                   Evaluates to the current time                       2012-12-24 20:00:00 +0200
+
+*$(Hostname)*                               Evaluates to the hostname                           MY_COMPUTER
+
+*$(CPPPath)*                                Evaluates to the base path of the                   /usr/bin
+                                            c++ compiler
+
+*$(CPath)*                                  Evaluates to the base path of the                   /usr/bin
+                                            c compiler
+
+*$(ASMPath)*                                Evaluates to the base path of the                   /usr/bin
+                                            assembler
+
+*$(ArchiverPath)*                           Evaluates to the base path of the                   /usr/bin
+                                            archiver
+
+*$(LinkerPath)*                             Evaluates to the base path of the                   /usr/bin
+                                            linker
+
+*$(/)*                                      Evalutes to the directory path seperator of         Windows: \\, Other: /
+                                            the current platform
+
+*$(:)*                                      Evaluates to the path variable seperator            Windows: ;, Other: :
+                                            of the current platform
+========================================    ===============================================     ========================================
+
+.. tip:: 
+
+    It is also possible to retrieve arbitrary an *environment variable* using the following syntax:
+
+    .. code-block:: console
+        
+        $(EnvironmentVariable)
+
+    Evaluates to the Environment with the specified name, if the specified environment variable does not exists
+    it will be substituted by an empty string.
+
+.. note::
+
+    Equal variables in the main config
+
+    ========================================    ========================================
+    Variable                                    Is equal to 
+    ========================================    ========================================
+    $(MainConfigName)                           $(ConfigName)
+
+    $(MainProjectName)                          $(ProjectName)
+    ========================================    ========================================
+
+.. warning::
+
+    Variables in Dependency definitions are not allowed!
+
+
+Nested variables
+****************
+It is also possible to nest variables.
+
+Example:
+
+.. code-block:: console
+    
+    $(OutputDir,$(TheProject),$(TheConfig))
+    $(ABC$(DEF)GH)
+
+
+Auto-adjustment of paths to existing projects
+*********************************************
+.. warning::
+
+    If paths to other projects are needed, e.g. to "bootloaderUpdater", don't write a hard coded relative path like this:
+    
+    .. code-block:: text
+
+        CommandLine "../bootloaderUpdater/tools/PrimaryBootloader2Include.exe
+
+If paths to other projects are needed, e.g. to "bootloaderUpdater" just reference it starting from the project folder.
+
+Example:
+
+.. code-block:: text
+
+    CommandLine "bootloaderUpdater/tools/PrimaryBootloader2Include.exe
+
+or:
+
+.. code-block:: text
+
+    IncludeDir "myProjectName/bootloaderUpdater/whatever"
+
+
+
+bake recognizes that the first part of the path is a valid project name and calculates the relative path to the project automatically.
+If you have the special case that the referenced project is contained in an other workspace root, you can use the 
+`-w` parameter or you define a `roots.bake`.
+
+.. note::
+
+    The path auto adjustment is applied for the following elements:
+
+    * IncludeDir
+
+    * ExternalLibrary
+
+    * ExternalLibrarySearchPath
+
+    * UserLibrary
+      
+    * CommandLine
+

data/documentation/_build/html/_sources/tips_and_tricks/how_to_use_bake_with_cygwin.txt

@@ -0,0 +1,49 @@
+How to use bake with cygwin
+===========================
+Why using Cygwin on Windows instead of the built-in command shell? 
+There is one major reason: Cygwin supports **colored output** via ansi escape sequences. 
+Note, that these steps differ depending on the Cygwin version, installed packages and configuration.
+
+#. Get rid of the cygdrive prefix
+
+    .. image:: ../_static/cygwin_mount.png
+        :width: 100 %
+        :scale: 50 %
+
+    As you see, "c:" is now "/c" and not "/cygdrive/c" anymore. 
+
+    .. note::
+
+        In newer Cygwin versions, this is not permanent. To make it permanent, 
+        add the following line to /etc/fstab (can be found in your Cygwin installation directory):
+
+        .. code-block:: console
+            
+            none / cygdrive binary,posix=0,user 0 0
+
+#. Get rid of the Cygwin ruby
+
+    .. image:: ../_static/cygwin_ruby.png
+        :width: 100 %
+        :scale: 50 %
+   
+    Easiest way is to rename the Cygwin ruby, which makes the original ruby visible. 
+    This is only necessary if you have ruby installed in our Cygwin environment.
+
+#. Add tty to CYGWIN option
+
+    .. image:: ../_static/cygwin_tty.png
+        :width: 100 %
+        :scale: 70 %
+
+    "tty" must be added to the CYGWIN system variable.
+
+#. Start the build
+
+    Use the parameter "-a black" or "-a white" depending on the background color of your shell.
+    Depending on your Cygwin installation, you have to call "bake.bat" instead of "bake". To avoid this, create an alias, e.g:
+
+    .. code-block:: console
+
+        alias bake=/c/Programme/_dev/Ruby192/bin/bake.bat
+

data/documentation/_build/html/_sources/tips_and_tricks/static_code_analysis.txt

@@ -0,0 +1,122 @@
+Static Code Analysis
+====================
+
+Static code analysis often is part or a pre step of the build, even though bake provides presteps which can be used to 
+add customized steps, we choose to add explicit support for static code analysis due to the fact that the analysis often
+depends on information well known by the build system (include pahts, compiler flags, etc.). Currently bake has  built in
+support for *Pc-Lint*. 
+
+Lint
+****
+
+With bake you can lint LibraryConfigs, ExecutableConfigs, single files and the complete workspace (in this case the projects are linted separately). 
+The CPP Toolchain settings of the project are used regardless of the file type and file specific options. 
+It is possible to specify lnt-files with LintPolicy, but you can add every other lint command line option as well.
+
+Basic Setup
+-----------
+
+#. Install `lint  <http://www.gimpel.com/html/products.htm>`_.
+#. Make sure the The lint executable 'lint-nt.exe' is in the path.
+
+.. attention::
+
+    even though there is a unix version of pc-lint the asscoated binary name must be lint-nt.exe otherwise
+    it won't be recorgnized by the bake build system.
+
+After doing this steps you are able to lint your build configurations (LibraryConfigs and ExecutableConfigs) using the *--lint* flag on the command line.
+
+Example
++++++++
+.. code-block:: console
+
+    User@Host:~$ bake Debug -p MyLibraryProject --lint
+
+
+Configuring Lint
+----------------
+
+In order to configure lint in the Project.meta file, just use the *LintPolicy* command, which forwards the supplied
+the parameters to lint.
+
+.. code-block:: text
+
+    DefaultToolchain GCC {
+        ...
+        LintPolicy "$(ProjectDir)/lint/misra.lnt"
+        LintPolicy "$(ProjectDir)/lint/suppressions.lnt"
+    }
+
+Example
++++++++
+
+This example shows how to redirect the output to single xml files placed into the main project folder.
+
+.. code-block:: text
+
+    DefaultToolchain GCC {
+        LintPolicy "-os($(MainProjectDir)/$(ProjectName)_$(ConfigName)_lintout.xml)"
+        LintPolicy "-v"
+        LintPolicy "+xml(doc)"
+        LintPolicy "-format=%f %l %t %n %m"
+        LintPolicy "-format_specific= "
+        LintPolicy "-pragma(message)"
+        ...
+    }
+
+
+Known Issues
+------------
+bake only searches for lint-nt.exe
++++++++++++++++++++++++++++++++++++
+    **Issue:**
+    bake currently does not search for all possible names of the lint application, it only searches for a file called *lint-nt.exe*.
+
+    **Solution:**
+    If you have another lint command (e.g. because you are using flexe lint on unix)
+    just create an symlink/alias which is called *lint-nt.exe*.
+
+Lint fails due to missing compiler includes and defines 
++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+    **Issue:**
+    Lint will fail if compiler internal includes and defines are missing. 
+
+    **Solution:**
+       
+    Lint comes with some helper files, handle this issue. In order to get a list of all needed
+    helper files e.g. for GCC, use the following command. 
+
+    .. code-block:: console
+
+        User@Host:~$ make -f .../PcLint/../lnt/co-gcc.mak
+
+    You will get a output like this:
+
+    .. code-block:: text
+
+        gcc-include-path.lnt, lint_cmac.h, lint_cppmac.h and size-options.lnt.
+
+    You can now add the needed includes and LintPolicies (.lnt files) to your bake 
+    configuration.
+
+Lint error due to too many includes
++++++++++++++++++++++++++++++++++++
+
+    **Issue:**
+    In rare cases lint has problems if it has to open too many (include) files. 
+
+    **Solution:**
+    You can use the *--lint_max* and the *--lint_min* options to get around this issue.
+
+    Example:
+
+    .. code-block:: console
+
+        User@Host:~$ bake Debug -p MyLibraryProject --lint --lint_max 50                 #(lints the first 51 files)
+        User@Host:~$ bake Debug -p MyLibraryProject --lint --lint_min 51 --lint_max 100  #(lints the next 50 files)
+        User@Host:~$ bake Debug -p MyLibraryProject --lint --lint_min 101                #(lints the rest of the files)
+
+
+.. Clang Analyze
+.. *************
+