Records

Records are written using YAML syntax. There are 3 types of records

1. Projects list file (usually projects.yaml)
2. Project definition file (the main project file which defines name of the project, board..)
3. Module file (a module of source files and include paths)

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

### 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.

projects:
    k20_blinky:
        - records/common.yaml
        - records/k20_cmsis.yaml
        - records/k20_target.yaml
        - records/projects/k20_blinky.yaml
    lpc1768_blinky:
        - records/common.yaml
        - records/lpc1768_cmsis.yaml
        - records/lpc1768_target.yaml
        - records/projects/lpc1768_blinky.yaml

### Settings in the projects list file

If you want to use build feature, the paths need to be set, in case the default one don't match your settings.

This are the default settings (taken from settings script file):

        def __init__(self):
        """ This are default enviroment settings for build tools. To override,
        define them in the projects.yaml file. """
        self.paths = {}
        self.paths['uvision'] = os.environ.get('UV4') or join('C:', sep,
            'Keil', 'UV4', 'UV4.exe')
        self.paths['iar'] = os.environ.get('IARBUILD') or join(
            'C:', sep, 'Program Files (x86)',
            'IAR Systems', 'Embedded Workbench 7.0',
            'common', 'bin', 'IarBuild.exe')
        self.paths['gcc'] = os.environ.get('ARM_GCC_PATH') or ''

To overwrite for example uvision path, define the the projects.yaml file:

projects:
    your projects defined here

settings:
    tool:
        uvision:
            path:
                - /usr/desktop/armcc/bin-5.0.3/

### Project definition file

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

common:
    target:
        - mbed-lpc1768
    include_paths:
        - examples/blinky
    source_files:
        - examples/blinky/main.cpp
    macros:
        - TARGET_LPC1768

### 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.

common:
    group_name:
        lpc1768_cmsis
    include_paths:
        - targets/cmsis/TARGET_NXP/TARGET_LPC176X
    source_files:
            - targets/cmsis/TARGET_NXP/TARGET_LPC176X/cmsis_nvic.c
tool_specific:
    gcc_arm:
        source_paths:
            - targets/cmsis/TARGET_NXP/TARGET_LPC176X/TOOLCHAIN_GCC_ARM
        source_files:
            - targets/cmsis/TARGET_NXP/TARGET_LPC176X/TOOLCHAIN_GCC_ARM/startup_LPC17xx.s
        linker_file:
            - targets/cmsis/TARGET_NXP/TARGET_LPC176X/TOOLCHAIN_GCC_ARM/LPC1768.ld

Records attributes

### Common attributes

Common attributes are generic, so any file, macro or path defined as common, will be be available for any tool selected.

common:
    group_name:
        - my_new_group
    source_files:
        - source.c
        - assembly_file.s
    macros:
        - MY_NEW_MACRO

Available common attributes:

• target - the platform to be used. This serves as an entry for specific MCU and its settings for tools. There's board definition file, where you can add a new board, and then MCU definitions
• group name - name of the group (virtual dir), used by IDE to group files
• include_paths - include paths
• source_paths - source paths (optional, not currently used as it is derived from sources)
• source_files - source files (can be a folder - all files added or specified source files)
• source_files_obj - object files
• source_files_lib - libraries
• macros - macros
• project_dir - the export path. It should define name and path

### Tool specific attributes

They are used to set tool specific options. As an example, each tool has own the linker command file. If there's a project supported at least 2 tool they need to specify a linker command file for each tool.

tool_specific:
    source_files:
        - source.c
        - assembly_file.s
    linker_file:
        - linker.ld
    macros:
        - MY_NEW_MACRO
    misc:
        optimization:
            - O3

Available tool_specific attributes:

• linker_file - linker command file
• source_paths - source paths - are optional, not used currently
• include_paths - include paths
• source_files - source files (any of .c, .cpp, .s)
• source_files_obj - object files
• source_files_lib - libraries
• mcu - MCU name as defined in the tool (each tool has different naming). This can overwrite board definition. For example if you have a specific MCU, use this option to define MCU
• macros - tool specific macros
• misc - this is a dictionary of all available options. The content depends on selected toolchain. Look at the specific tool wiki page for available options.
• project_dir - the export path. It should define name and path