Getting_started

By default, the project generator is set to be placed 2 folders deep from root. Like project_root/tools/project_generator. This dependency is set in the default settings (PROJECT_ROOT). So if you want to place it anywhere else, create user_settings script file and change PROJECT_ROOT path.

Step 1 (optional if you haven't changed PROJECT_ROOT) Firstly, create a tools directory in your project root. Navigate inside tools, where you clone this repository. You can create a submodule within your current project. To read more about submodule, visit link or look at the example provided : Git submodules

Clone the repository to tools directory:

project/tools> git clone https://github.com/0xc0170/project_generator.

This is how the directory tree for project generator should look like

+---project
    +---folders
    +---tools
        +---project_generator
        +---records

There is the folder records. What does it include? There should be defined records for projects. The location can be anywhere, but recommended to be in tools as they are bounded to project_generator.

What is it record?

Record is YAML file which describes a project as a list of modules. There should be a file with a project/all projects. Each project has own record, to describe requirements for the project. The project consists of modules. A module is a list of files, which share same attributes.

Projects list file It defines all projects available for repository. It can consist of one or more projects. Each project includes other records - one project definition file and many modules.

Project definition file This is a unique record file. It defines specific attributs for specified project.

A module file This is a file which defines a module. A module is bunch of files with common attributes. For instance, if there are target specific files, we can create a new module named target_specific.yaml file and define all attributes specific for that module.

Once you set up records (list of projects, project file and modules), start using export script to generate projects.

Important note, all paths in records require to be defined with a full path (from the root directory).

Create records for a project

As a first step, create a record of projects list file.

kl25z_blinky:
    - tools/records/kl25z_cmsis.yaml
    - tools/records/kl25z_target.yaml
    - tools/records/kl25z_blinky.yaml

There is one project defined, named kl25z_blinky. It consists of 3 modules (3 yaml records).

How does kl25z_blinky projects list file look like?

core:
    - cortex-m0+
common:
    include_paths:
        - examples/blinky
    source_paths:
        - examples/blinky
    source_files:
        - examples/blinky/main.cpp
    macros:
        - ALLOWED_GENERIC_TICKER
tool_specific:
    uvision:
        mcu:
            - MKL25Z128xxx4
        macros:
            - MY_NICE_MACRO_VALID_ONLY_FOR_UVISION
        misc:
            Cads:
                MiscControls:
                    - --debug
                    - -g
                    - --gnu
                Optim:
                    - 1
                uC99:
                    - enable
                OneElfS:
                    - enable
    gcc_arm:
        mcu:
            - MKL25Z128xxx4
        misc:
            libraries:
                - m
                - nosys
            optimization:
                - O1
            compiler_options:
                - g
                - ggdb
                - Wall
                - fno-strict-aliasing

The KL25Z blinky project is defined for uVision and GCC ARM. There are common attributes (generic) and tool specific. Each ide has own attributes, which are parsed by specific ide parser class. The common attributes are parsed by yaml parser class. The other 2 yaml records file (cmsis, target) follow the same syntax, they define linker file, core files and target specific files as a driver for kl25z for example. Once we have records defined, we should be able to generate a project.

How to generate a project

All scripts should be run from the projects tools directory

There's main file export.py, which accepts arguments. For more help, type export.py --help, to see all available options.

Available arguments for export.py are :

"-f", "--file", help="YAML projects file")
"-p", "--project", help="Project to be generated")
"-t", "--tool", help="Create project files for tool (uvision by default)")
"-l", "--list", action="store_true", help="List projects defined in the project file.")
"-b", "--build", action="store_true", help="Build defined projects."

The parameter --file sets the project file, which defines a project/or list of projects to be generated. To select only one project to generate, use also -p argument.

For instance, to generate all projects within projects.yaml file, run it as follows:

project/tools>python project_generator/export.py -f records/projects.yaml

The projects are genereted by default in the root directory, under the generated_projects. Once project/projects generated, they can be built. Use argument -b to build them. This feature is usefull for automated testing for example.

To redirect the export output, define project_dir in the project:

common:
    project_dir:
        path:
            - example/blinky
tool_specific:
    uvision:
        project_dir:
            name:
                - uvision
        mcu:
            - MKL25Z128xxx4

The code above redirects the export to example/blinky/uvision for uvision tool. The name can be also set in the common area.

More information

For further information, how to add a new MCU, a new IDE, or how data are parsed, look at the other available wiki pages.

Sharing is caring - If you find an issue, any limitation, or possible improvements, please report it here on github. Any feedback is appreciated !