Templating #80

nopeslide · 2020-11-29T20:51:51Z

Related Issues & PRs

none

Description

templating mechanism via Makefiles
port existing templates

Context

It should be as easy as possible to add new content to the repository,
therefore I propose a general templating mechanism, integrated into the Makefile system, so it can be used anywhere.

A .template.mk can be created in any directory managed by our build system and describes what templates exist in this direcory.
This could look like this

# add <NAME> to available template options
TEMPLATING_CHOICES   += <NAME>
# set a  help message for the make help screen
TEMPLATING_HELP_<NAME> := create a new <NAME>
# what directories and files should be used 
TEMPLATING_PATH_<NAME> += dir/to/template
# any extra varaibles which the template may use
TEMPLATING_VARS_<NAME> += <VAR>

# default value of the variable
<VAR>      := default_value
# help message of the variable
HELP_<VAR> := Sets the <VAR> variable

make now knows about this template an proposes it when executing make new

$ make new
--- help for target new ---
LifeSensor Makefile

--- new targets ---
make new-<NAME>
    create a new <NAME>

--- Common template options ---
NAME
    how to rename the template
    (currently: )

--- 'new-<NAME>' template options ---
<VAR>
    Sets the <VAR> variable
    (currently: default_value)

Template files are copied to directory specified by NAME.
If a file ends with a specific suffix like .m4 or .envsubst the corresponding tool is run over the file and the suffix removed.
Any variable used by the template is propagated to the tool and can be directly used in the file
I.e.
when running something like make new-foo NAME=test
the file README.md.envsubst in the template dir with the content

# README of ${NAME}
...

becomes the file README.md with the content

# README of  test
...

Testing

initial draft tests
further tests

Documentation

document how to create and use templates

Now follows an excerpt of all added READMEs: General repository structure ---------------------------- - The project consists of *components* - *Components* reside inside the root of the repository - All *component* directories should feature a README.md - All *component* directories should feature a Makefile lifesensor │ ├── README.md : main README.md of the project ├── Makefile : Makefile executing targets in all components │ ├── CONTRIBUTING.md : information on how to contribute ├── LICENSE.md : license information │ ├── docs │ ├── README.md : list & description of project documents │ ├── Makefile : Makefile building/generating documents │ └── ... │ ├── <component name> : component name │ ├── README.md : general description of the component, │ │ its structure and a list of all subcomponents │ ├── Makefile : Makefile executing targets in all subcomponents │ │ │ ├── <subcomponent name> : subcomponent name │ │ ├── README.md : general description of the subcomponent │ │ │ and list of all subcomponent variants │ │ ├── Makefile : Makefile bundeling all variants │ │ │ │ │ ├── docs │ │ │ ├── README.md : list & description of subcomponent documents │ │ │ ├── Makefile : Makefile building/generating documents │ │ │ └── ... │ │ │ │ │ ├── <variant> : a variant is a non-exchangeable component │ │ │ ├── README.md : general description of the variant │ │ │ ├── Makefile : Makefile integrating component toolchain │ │ │ │ │ │ │ ├── docs │ │ │ │ ├── README.md : list & description of variant documents │ │ │ │ ├── Makefile : Makefile building/generating documents │ │ │ │ └── ... │ │ │ └── ... │ │ │ │ │ ├── <variant> │ │ │ └── ... │ │ └── ... │ │ │ ├── <subcomponent name> │ └── ... │ ├── <component name> │ └── ... └── ... - A README.md should link to all subdirectories that contain a README.md - Links to directories should always end with a slash (`/`) - Links should always have a relative prefix (`./`,`../`, ... ) - All README.md's should describe important Makefile targets - All README.md's should describe the structure of subdirectories - All Makefiles should support the common targets. - `help` - show information about targets and variables - `all` - run common jobs (like `build` & `test`) - `check` - run all check jobs - *check* jobs are environment validations - I.e. check if toolchain is installed - `setup` - run all setup jobs - *setup* jobs are environment configurations - I.e. define devices to flash - `build` - run all build jobs - should not be dependent on any `setup` target - `test` - run all test jobs - should not be dependent on any `setup` target - `clean` - delete everything build - `distclean` - delete everything generated - should reset the state prior execution of any target - All Makefiles should integrate Makefiles in subdirectories. - Targets that fall in one of these target categories should be named `<category>-<target>`. - I.e. `build-library`, `clean-library`, `test-library`, ... - A Makefile should include the [.common.mk](./.make/common.mk) Makefile to define these common targets. - simply add `include $(shell git rev-parse --show-toplevel)/.make/common.mk` as last statement in the Makefile. Docker component structure -------------------------- lifesensor/docker ├── README.md : mandatory README.md you are currently reading ├── Makefile : mandatory Makefile executing targets in all subdirs │ ├── <image name> : mandatory unique name of the image │ ├── README.md : mandatory general description of the image │ │ and elaboration of differences between version │ ├── Makefile : mandatory Makefile executing targets in all subdirs │ │ │ ├── <image version> : mandatory unique image version │ │ ├── README.md : mandatory version specific description of the image, │ │ │ should list all features │ │ ├── Makefile : mandatory Makefile for integration of the image │ │ ├── Dockerfile : mandatory Dockerfile to build image │ │ └── ... │ │ │ ├── <image version> │ │ └── ... │ └── ... │ ├── <image name> │ └── ... └── ... - *Docker images* of the LifeSensor project should have a dedicated directory here. - *Docker images* can be based on each other (see [base](./base/) image). - *Docker images* may compete for the same functionality. - Different [*parts*](../parts/) may use different *docker images* - *Docker images* should follow the directory scheme defined by the [*template image*](./.template/) - *Docker images* may contain any additional files & directories Parts component structure ------------------------- lifesensor/parts ├── README.md : mandatory README.md you are currently reading ├── Makefile : mandatory Makefile executing targets in all subdirs │ ├── <part name> : mandatory unique name of the part │ ├── README.md : mandatory general description of the part │ │ and elaboration of differences between version │ │ │ ├── <part version> : mandatory unique part version │ │ ├── README.md : mandatory version specific description of the part, │ │ │ should list all features │ │ │ │ │ ├── Makefile : mandatory Makefile for integration of the part │ │ │ │ │ ├── code : optional parent directory of any source code and build system files │ │ │ │ i.e. firmware │ │ │ ├── README.md : description of the source code │ │ │ └── ... │ │ │ │ │ ├── docs : optional parent directory for documents │ │ │ │ i.e. documentation, datasheets │ │ │ ├── README.md : description of documents │ │ │ └── ... │ │ │ │ │ ├── kicad : optional parent directory for kicad files │ │ │ │ i.e. project files, schematics │ │ │ ├── README.md : description of the kicad files │ │ │ └── ... │ │ │ │ │ ├── mechanics : optional parent directory for mechanic files │ │ │ │ i.e. 3D-printer models │ │ │ ├── README.md : description of the mechanics files │ │ │ └── ... │ │ │ │ │ ├── requirements : mandatory parent directory for requirements │ │ │ │ used by requirement management tools │ │ │ ├── README.md : description of requirements │ │ │ └── ... │ │ │ │ │ └── scripts : optional parent directory of part specific helper scripts │ │ │ i.e. documentation generation, calculators │ │ ├── README.md : description of scripts │ │ └── ... │ │ │ ├── <part version> │ │ └── ... │ └── ... │ ├── <part name> │ └── ... └── ... - *Parts* of the LifeSensor project should have a dedicated directory here. - *Parts* should not include other *parts*, instead they should refer to other *parts*. - *Parts* may compete for the same functionality. - Different [*products*](../products/) may choose different *parts* - *Parts* should follow the directory scheme defined by the [*template part*](./.template/) - *Parent directories* may contain any structure - Optional *parent directories* can be removed - Only non-breaking changes may be introduced as patch for a *part* - *Part versions* denote non-backwards-compatible variants of the same *part* - If major implementations change, consider creating a new *part* or *part version* - *Part versions* should never denote the state of the *part* - All *part versions* should provide their intended functionality Products component structure ---------------------------- lifesensor/products │ ├── README.md : mandatory README.md you are currently reading ├── Makefile : mandatory Makefile executing targets in all subdirs │ ├── <product name> : mandatory unique name of the product │ ├── README.md : mandatory general description of the product │ │ and elaboration of differences between version │ │ │ ├── <product version> : mandatory unique product version │ │ ├── README.md : mandatory version specific description of the product, │ │ │ should list all features │ │ │ │ │ ├── Makefile : mandatory Makefile for integration of the product │ │ │ │ │ ├── docs : optional parent directory for documents │ │ │ │ i.e. documentation, datasheets │ │ │ ├── README.md : description of documents │ │ │ └── ... │ │ │ │ │ └── requirements : mandatory parent directory for requirements │ │ │ used by requirement management tools │ │ ├── README.md : description of requirements │ │ └── ... │ │ │ ├── <product version> │ │ └── ... │ └── ... │ ├── <product name> │ └── ... └── ... - *Products* of the [*LifeSensor*](https://lifesensor.org) project should have a dedicated directory here. - *Products* should not include [*parts*](../parts/) or other *products* - *Products* may compete for the same functionality. - Different *products* may choose different [*parts*](../parts/) to achieve the same - *Products* should follow the directory scheme defined by the [*template product*](./.template/) - *Parent directories* may contain any structure - Optional *parent directories* can be removed - Only non-breaking changes may be introduced as patch for a *product* - *Products versions* denote non-backwards-compatible variants of the same *product* - If major implementations change, consider creating a new *product* or *product version* - *Products versions* should never denote the state of the *product* - All *product versions* should provide their intended functionality

nopeslide and others added 12 commits November 8, 2020 13:45

moved files for new repo structure

2b7fe87

made help of variables target-aware

c199072

added templating mechanic to Makefiles

22605d2

removed warning print in help.mk

0c6627b

fixed m4 invoktion

42b78e1

made error printing more readable

16dcf04

modified part template for new templating mechanism

10de7da

added envsubst templating

28b5006

fixed sed pattern

3f04cfb

fix sed pattern

8048e5d

replaced for loop bash construct with seq

d3645ad

nopeslide requested review from ikstream and jhonnyam November 29, 2020 20:52

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Templating #80

Templating #80

nopeslide commented Nov 29, 2020 •

edited

Loading

Templating #80

Are you sure you want to change the base?

Templating #80

Conversation

nopeslide commented Nov 29, 2020 • edited Loading

Related Issues & PRs

Description

Context

Testing

Documentation

nopeslide commented Nov 29, 2020 •

edited

Loading