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 notes about records:

• all paths in records require to be defined with a full path (from the root directory).
• use backslash or forward slashes in paths, all paths are normalized based on the tools requirement
• everything is a list in yaml file
• common is valid for any tool (thus named common)
• tool_specific depends on the tool
• use valid YAML syntax

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

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

YAML provides anchors and references. They can be used to create "modules" - a groups of yaml files. This feature can be used within projects.yaml file. Illustration: Both projects using common.yaml file. Let's create a module common, where all common records are going to be placed.

# modules is not required but nicer to have it grouped
modules:
  # &name is an anchor which can be later referenced
  common: &common_module
  - records/common.yaml
  - records/anyotherrecord.yaml

projects:
  k20_blinky:
  - *common_module

common_module reference (*common_module) is expanded to a list of all yaml files. This enables to group records.

### 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('UV5') or join('C:', sep,
            'Keil', 'UV5', 'UV5.exe')
        self.paths['iar'] = os.environ.get('IARBUILD') or join(
            'C:', sep, 'Program Files (x86)',
            'IAR Systems', 'Embedded Workbench 8.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-6.13.0/

### Project definition file

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

common:
  target:
  - mbed-lpc1768
  includes:
  - examples/blinky
  sources:
  - examples/blinky/main.cpp
  - source/direc
  macros:
  - TARGET_LPC1768

All valid source files will be added to source files from source directory.

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

common:
  includes:
  - targets/cmsis/TARGET_NXP/TARGET_LPC176X
  sources:
    lpc1768_cmsis:
    - targets/cmsis/TARGET_NXP/TARGET_LPC176X/cmsis_nvic.c
tool_specific:
  gcc_arm:
    sources:
    - 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
  sources:
    my_new_group:
    - source.c
    - assembly_file.s
  macros:
  - MY_NEW_MACRO

Available common attributes:

• target - the platform to be used or mcu. Please look at progen definitions for available targets/mcu
• includes - include files/folders. They can be grouped (virtual directories)
• sources - source files - code, object files or libraries (can be a folder - all files added or specified source files). They can be grouped (virtual directories)
• macros - macros
• export_dir - the export path. It should define name and path
• build_dir - directory for output (build directory)
• debugger - debugger selection
• output_type - executable or library
• tools_supported - tools which are supported by a project

### 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:
  sources:
  - source.c
  - assembly_file.s
  linker_file:
  - linker.ld
  macros:
  - MY_NEW_MACRO

Available tool_specific attributes:

• linker_file - linker command file
• includes - include files/folders
• sources - source files/folders
• macros - macros
• export_dir - the export path
• template - template project file (.ewp, .uvprojx or any other tool project file)

misc attributes (should be placed under tool_specific):

• common_flags - applied to all (including linker, asm, etc. See below flags)
• ld_flags - linker flags
• asm_flags - assembler flags
• c_flags - C flags
• cxx_flags - C++ flags

### Project record with all options

common:
  # Output - exe or lib
  output:
  - lib

  #Tools supported by this project - optional. Enables to use progen export and this tools
  # are used for this project only
  tools_supported:
  - iar_arm
  - make_gcc_arm
  - coide
  - uvision

  # Choose a debugger
  debugger:
  - j-link

  # Export directory
  export_dir:
  - projects

  target:
  - mbed-lpc1768 #lpc1768 is also valid (=mcu)

  includes:
  - examples/blinky

  sources:
  - examples/blinky/main.cpp

  macros:
  - TARGET_LPC1768
  - TARGET_M3

tool_specific:
  uvision:
    macros:
    - MACRO_FOR_UVISION
    # use this project file
    template:
    - project.uvproj
    misc:
      cxx_flags:
      - --gnu

    iar:
      template:
      - project.ewp
      misc:
        asm_flags:
        - --some_valid_asm_flag

    coide:
      template:
      - project.coproj

    # makefile dont currently support any template. Cmake could help us here?
    make_gcc_arm:
        macros:
        - TOOLCHAIN_ARM_GCC
        misc:
          standard_libraries:
          - c
          - nosys
          common_flags:
          - -O1
          - -g
          - -ggdb
          - -Wall
          - -fno-strict-aliasing

### Main projects record with all options

projects:
  project_1:
  - files.yaml
  - settings.yaml
  projecct_2:
  - files2.yaml
  - settings.yaml
  project_3:
  - sources.yaml

settings:
  tools:
    coide:
      template:
      - records/templates/template.coproj

    iar:
      template:
      - records/templates/template.ewp
      path:
      - path_to_iar #used for building
    uvision:
      template:
      - records/templates/template.uvproj
      path:
      - path_to_uvision #used for building

  # change default output dir (generated_projects to a path with keywords)
  export_dir:
  - generated_projects/{target}/{project_name}/{tool}