Project Setup Guide
Headroom needs to know where to search for configuration, template and source code files. If you plan to use Headroom regularly for your project, you might want to keep template files and configuration together with your project, but there's also option to run Headroom completely without any need to generate any files.
Running Without Initialization¶
If you only plan to use Headroom occasionally or just don't want have any additional files in your project, you can completely skip initialization and specify all required things using command line options, like this:
headroom run --builtin-templates bsd3 -s src -v "author=John Smith" -v "email=john.smith@tardis.co" -v "project=Project Name" -v "year=2020"
See the Running Headroom chapter for more details.
Automatic Initialization (for OSS projects)¶
Easiest and fastest way how to initialize Headroom for your project is to use the init
command, which generates all the boilerplate for you. The only drawback is that you can use it only in case that you use any supported open source license for which Headroom contains license header templates:
cd project/
headroom init -l bsd3 -s src/
This command will automatically scan source code directories for supported file types and will generate:
1. .headroom.yaml
configuration file with correctly set path to template files, source codes and will contain dummy values for variables.
1. headroom-templates/
directory which contains template files for all known file types you use in your project and for open source license you choose.
Now the project structure will be following:
project/
├── src/
│ ├── scala/
│ │ ├── Foo.scala
│ │ └── Bar.scala
│ └── html/
│ └── template1.html
├── headroom-templates/
│ ├── html.mustache
│ └── scala.mustache
└── .headroom.yaml
Manual Initialization¶
If you for some reason don't want to use the automatic initialization using the steps above, you can either create all the required files (YAML configuration and template files) by hand, or you can use the gen
command to do that in semi-automatic way:
cd project/
headroom gen -c >./.headroom.yaml
mkdir headroom-templates/
cd headroom-templates/
headroom gen -l bsd3:css >./css.mustache
headroom gen -l bsd3:html >./html.mustache
headroom gen -l bsd3:scala >./scala.mustache
After these steps, make sure you set correctly the paths to template files and source code files in the YAML configuration file.