Project Settings
Each project that is supported by the Ensono Stacks CLI have a settings file associated with them. This is called, by default, stackscli.yml
. It is possible to override the actual file that is used as well as the filename.
The settings file is intended to allow the project maintainers to define what steps needs to be done on a project and instruct the CLI what to do, without having to refactor the CLI.
Structure
The following table details the structure of the settings file.
Parameter | Description | Example | Allowed Values |
---|---|---|---|
framework | The framework that the project is based on. | ||
pipeline | This is a list of the supported pipelines and the associated files | ||
init.operations | List of operations that need to be performed on the temporary project directory | ||
setup.operations | List of operations that need to be performed on the project directory |
Settings file root structure
The following table shows the options that can be specified for a framework
Parameter | Description | Example | Allowed Values |
---|---|---|---|
| Name of the framework that this project targets |
|
|
A list of the commands and the versions that are required for the project This is a list, so multiple commands and versions can be specified in the yaml file |
| ||
Name of the command to be checked |
| ||
| This is a semantic version constraint that the command version must conform to So to ensure that the |
| Any valid semver constraint |
Note
If no command or version is specified then the command that is found on the machine that the CLI is running on will be used without checking.
Important
It is possible to ignore the results of the version check when the CLI is running by using the
force
option, but remember that it is a destructive operation and it will delete any existing projects that exist in the same path.
Not all version numbers conform to semantic versioning. For example Java tends to add characters to the version number, e.g. 1.8.0_301
. To get around this the CLI tries to make the version semver compliant by removing the _
, so the version tested will be 1.8.0301
which is a valid semver.
The next table shows the options for the operations.
Note
These are valid for both
init
andsetup
operations
Parameter | Description | Example | Allowed Values |
---|---|---|---|
| The type of action that needs to be performed If |
|
|
| The command that needs to be run. Each framework has a set of commands that it knows it can during the setup of the project run. The value that is set here must be specified within that list in order for the command to execute. | java = dotnet = nx = | |
| The arguments that need to be passed to the command |
| |
| Description of what is being performed. This is output during the execution of the CLI | Installing template from folder |
The follow table shows the values that can be assigned to the pipeline list.
Parameter | Description | Example | Allowed Values |
---|---|---|---|
| Type of pipeline being configured |
|
|
| List of files that should be worked on. See File definition for syntax | ||
| List of templates that the CLI should use. At the moment only
| ||
| This is a list of replacements that need to be made in the build file |
Parameter | Description | Example |
---|---|---|
| Name of the file. The names The names must be unique, if not then the last one specified with the same name will take precedence. |
|
| Path to the file in question, relative to the repository root |
|
| If set to This is not supported when used in a |
|
Note
If no template is specified for the
variable
then the static version built into the CLI will be used. This can be seen in ???.
Parameter | Description | Example |
---|---|---|
pattern | Regular expression pattern for finding the text to be replaced | ^.*myvalue$ |
value | Value to replace the phrase that has been found by the pattern | Foo Bar |
Replacement definition
YAML File
The following code listing shows an example settings file.
Example project settings file.
framework:
name: dotnet
commands:
- name: dotnet
version: ">= 3.1, < 3.2"
pipeline:
- type: azdo
files:
- name: build
path: build/azDevOps/azure/azure-pipelines-netcore-k8s.yml
- name: variable
path: build/azDevOps/azure/azuredevops-vars.yml
replacements:
- pattern: ^.*myvalue$
value: Foo Bar
init:
operations:
- action: cmd
args: new stacks-docs -n {{ .Input.Business.Company }}.{{ .Input.Business.Domain }}
desc: Create a project using the "stacks-docs" project
setup:
operations:
-
Sets the framework that the commands should be run for
-
Specify the commands for which the version number should be checked
-
The name of the command to get the version number for
-
The version constraint that the version number should be checked against
-
Specify the pipeline that is being targeted
-
Name and path to the build pipeline file in the repository, for the specified pipeline system
-
Name and path to the variable template in the repository
-
List of replacements that should be made in the specified build file
-
Perform operations on the temporary project directory
-
List any number of operations that need to be performed
-
States the action that needs to be performed
-
The arguments that need to be passed to the framework command, in this case
dotnet
-
Description of the operation, this will be displayed in the log output when the CLI is executed
-
Define operations that need to be performed after the project has been created
This example shows one action that needs to be performed on the project before it has been created in the user specified working directory.
Examples
The GO template package is very powerful and allows advanced configuration in a settings file. This section shows some examples of what can be achieved.
Setting a default value
The framework properties that can be specified on a project allow extra information to be specified in the CLI configuration that is passed to the template. This information does not have to be set, but a default value maybe required in the template.
For example, in the stacks-dotnet-cqrs-events
project we need to be able to pass in servicebus
or eventhub
based on the selection from the user. However if this selection is not made then the project settings file should still work as expected. It is not possible to default the property to a known value as these properties will be used by other languages, so the value needs to have a default in the template.
To achieve this the or
template function needs to be used. This function takes values and will use the first value that has been set.
The following listing shows a snippet of the project settings file for a project.
Setting default value using Go template.
- action: cmd
cmd: dotnet
args: new stacks-cqrs-events-app -n {{ .Input.Business.Company }}.{{ .Input.Business.Domain }} -o {{ .Project.Directory.WorkingDir }} -e {{ or .Project.Framework.Properties.Prop1 "servicebus"}}
In this example all of the values for the parameters come from the .Input
or .Project
object (as detailed in the ??? section).
The last parameter to be set is defined as {{ or .Project.Framework.Properties.Prop1 "servicebus" }}
. This will set the -e
parameter to the value set in the property if that is set or default to "servicebus".