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:

     {{#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 PascalCase,
• 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.