espmake allows espmake.yaml files to repeat map keys declarations such as sensor: or switch: across files and merges them. It also allows the C preprocessor to operate on yaml.

espmake assists with managing multiple esphome project variants that share yaml source files. espmake also enables the sharing of pin definitions and configuration definitions between yaml and C / C++ files by enabling the use of C preprocessor directives inside espmake.yaml files. See lily.yaml, config.h and pins.h in the example directory.

espmake generates a new espmake.yaml file for each project variant. Project variants are built in the build/ directory by default. Project variants are selected using the PRJ make variable and named after the file specified without the suffix. For example, for "make PRJ=lily.yaml", the espmake.yaml file will be found in build/lily. If the PRJ file is set to esphome.yaml, the build for it will be in build/esphome.

The reason a new espmake.yaml is generated is because espmake runs the existing esphome project's yaml files through the C-preprocessor (cpp) and leaves it there available for review - and for esphome to process.

Once a yaml file is generated by the Makefile, esphome commands can be issued upon it, such as:

 esphome compile espmake.yaml
 esphome upload  espmake.yaml
 esphome logs    espmake.yaml

See 'esphome -h' for more details on esphome commands. There are also some convenience aliases that can be found in Bashrc.

espmake is basically just a Makefile which is manually copied into an existing esphome project directory and renamed "Makefile" to enable the make command to be run without arguments indicating the name of the Makefile to process.

Note that this manual installation procedure assumes that the destination project doesn't have a Makefile already. If it does, the rename can be skipped espmake can be used with 'make -f Makefile.espmake'.

To use espmake, activate the esphome venv environment and then source the espmake/Bashrc, which will set ESPMAKE_HOME and define some convenience aliases. This bash alias may be useful to place in ~/.bashrc, alias espmake='source ~/git/esphome/venv/bin/activate; cd ~/git/espmake; source ./Bashrc; cd myProject'

These Makefile variables can be changed from their defaults by either editting the Makefile or overriding them with an argument to make such as

make PRJ=init.yaml

espmake will remember the PRJ setting by storing it in ESPMAKE_HOME/.espmake_project so that it does not have to be specified afterwards.

The initial yaml file that #includes the others. It defaults to "esphome.yaml". To quickly get started using espmake, clone espmake and then copy the Makefile to the same directory as your esphome.yaml and type make. If your esphome yaml file is called something else, use "make PRJ=. After specifyiong PRJ= once, espmake will remember it since it stashes it in $ESPMAKE_HOME/.espmake_project.

Generated yaml can be deleted using 'make clean'. To remove the binary build created by esphome, use 'make realclean'.

There are some additional comments describing Makefile features in the Makefile.

There are some aliases in file Bashrc which may be helpful for issuing esphome commands. To dump the espmake config, try 'make print-config'.

espmake uses a github project called cpptext (https://github.com/maartenSXM/cpptext) to remove hash-style comments before running files through the c-preprocessor and it also uses it's Makefile fragments.

cpptext leverages yq to merge multiple declaration of esphome sections such as "sensor:" or "switch:". This allows #ifdefs to declare them in separate files conditionally and cpptext will merge them together for processing by esphome.

Thank you to Landon Rohatensky for the exemplary espmake.yaml file https://github.com/landonr/lilygo-tdisplays3-esphome used to demonstrate espmake configuration, build and also as used in the test subdirectory.

Thank you Mike Farah for yq. It is at https://github.com/mikefarah/yq.

The author has not attempted to use espmake with Visual Studio.

Note: on MacOS, you need GNU sed to run dehash.sh, which espmake invokes. To install GNU sed, please do this:

brew install gsed

and then add this line to your .bashrc:

export PATH="/opt/homebrew/opt/gnu-sed/libexec/gnubin:$PATH"

and then 'source .bashrc' or logout and log back in.