| # fx create | |
| The `fx create` command generates scaffolding for new projects. See `fx create --help` for | |
| usage details. | |
| ## Running tests | |
| The tests should be included in the build along with the `//tools/create` target. | |
| * Run all tests: `fx test //tools/create` | |
| * Run only golden tests: `fx test //tools/create/goldens` | |
| The golden projects have their unit tests run as well. To only run host tests, | |
| pass the `--host` flag to `fx test`. | |
| ## Adding a new project type | |
| 1. Add a new directory with the project type name under `//tools/create/templates/`. | |
| 2. Populate the directory with the intended project structure | |
| * Name all template files with the `.tmpl` extension or `.tmpl-<lang>` for | |
| language-specific template files. | |
| * Use `{{PROJECT_NAME}}` in a file/directory name to substitute the user's `PROJECT_NAME`. | |
| 3. Add your new template files to the `templates` target in | |
| `//tools/create/templates/BUILD.gn` and to `TEMPLATES` in | |
| `//tools/create/templates/templates.bzl`. | |
| 4. Add the project type to the help doc-string in `CreateArgs` in `//tools/create/src/main.rs`. | |
| 5. Create a golden project in `//tools/create/goldens`. | |
| * Use the `fx create` command to create a golden project, using the `--override-copyright-year 2020` | |
| flag. This makes sure that tests don't start failing in 2021+. | |
| 6. Add a `golden_test()` to `//tools/create/goldens/BUILD.bazel` and add it to | |
| the `host_tests` test suite in the same file. | |
| * See the existing tests for examples. | |
| * The test will generate a project and compare it with your golden project. | |
| * Execute the tests with | |
| `fx bazel test --config=host //tools/create/goldens:host_tests`. | |
| * If your project includes a `BUILD.bazel` file, it's its own Bazel | |
| package, and the golden test can only read the files that it exports. | |
| List every generated file in an `exports_files()` call in that | |
| template, wrapped in `{{#if EXPORT_ALL_FILES}}` so that it only appears | |
| in the golden project, and generate the golden project with | |
| `--export-all-files`. For example, see | |
| [`templates/driver-default/BUILD.bazel.tmpl-rust`](templates/driver-default/BUILD.bazel.tmpl-rust): | |
| ``` | |
| {{#if EXPORT_ALL_FILES}} | |
| exports_files( | |
| [ | |
| "BUILD.bazel", | |
| "README.md", | |
| "src/lib.rs", | |
| ], | |
| visibility = ["//tools/create/goldens:__pkg__"], | |
| ) | |
| {{/if}} | |
| ``` | |
| ## Templates | |
| ### Layout | |
| Each top-level directory in `//tools/create/templates` corresponds to a project type | |
| of the same name. | |
| Files with the `.tmpl` and `.tmpl-*` extensions in these directories are [handlebars] templates. | |
| Template expansion is performed on the templates and the directory structure is replicated in | |
| the new project directory. | |
| Templates with the `.tmpl` extension are language agnostic. | |
| Templates with the `.tmpl-<lang>` extension are expanded only when the user supplies the | |
| `--lang=<lang>` flag. | |
| Multiple languages can be supported in the same template directory. For instance, the | |
| `component-v2` command supports `cpp` and `rust` languages by having both a `BUILD.gn.tmpl-cpp` | |
| and `BUILD.gn.tmpl-rust` file. | |
| Partial templates are fragments of template files that can be included by other templates. | |
| Partial templates begin with `_` and can be included in a template with the `{{>name_of_partial}}` | |
| without the leading `_`. | |
| Only partial templates at the root or within the project type directory being executed are | |
| available to a template. | |
| E.g. file layout: | |
| * `templates/` | |
| - `_copyright.tmpl` | |
| - `component-v2/` | |
| * `_common.tmpl` | |
| When creating a project of type `component-v2`, the partial templates `_copyright.tmpl` and | |
| `component-v2/_header.tmpl` are visible and can be executed with `{{>copyright}}` and | |
| `{{>component-v2/header}}`. | |
| ### Variables | |
| The template expansion uses [handlebars] syntax. Expand a variable with the syntax `{{VAR_NAME}}`. | |
| The available variable names are: | |
| * `COPYRIGHT_YEAR`: Today's year, eg. 2020, for use in copyright headers, | |
| * `PROJECT_NAME`: The user-specified project name, | |
| * `PROJECT_PATH`: The path from the fuchsia root directory to the new project, | |
| * `PROJECT_TYPE`: The project-type as specified on the command line, e.g: 'component-v2'. | |
| * `TEMPLATE_PATH`: The path to the source template being executed. | |
| Path names are also treated as template strings and can contain [handlebars] syntax. | |
| Eg. `component/meta/{{PROJECT_NAME}}.cml.tmpl` with `PROJECT_NAME="foo"` expands to `meta/foo.cml`. | |
| #### Adding a new variable | |
| To make a new variable accessible to templates, add it to `TemplateArgs` in | |
| `//tools/create/src/main.rs`. | |
| ### Helpers | |
| Helper functions can be invoked with the syntax `{{helper VAR_NAME}}`. | |
| The available helper functions are: | |
| * `pascal_case`: Converts a string argument into *P*ascal*C*ase, | |
| * `snake_case`: Converts a string argument into snake*_*case, | |
| * `screaming_snake_case`: Converts a string argument into SCREAMING_SNAKE_CASE, | |
| #### Adding a new helper | |
| To make a new helper function accessible to templates, follow instructions in | |
| `//tools/create/src/template_helpers.rs`. | |
| [handlebars]: https://docs.rs/handlebars |