# Configuration Reference

The **`nmk-workspace`** plugin handles the configuration items listed in this page.

All of them are initiliazed with convenient default values, so that you don't need to setup them for a default working behavior. You can anyway override them in your project if you need to fine tune the plugin behavior.

## Subprojects listing

This configuration items are used to list current workspace project subprojects.

(workspaceSubModules)=
### **`workspaceSubModules`** -- raw submodules list

| Type | Default value |
|-     |-
| list[str]  | Generated by {py:class}`nmk_workspace.resolvers.SubProjectsResolver`

This is the recursive list of all relative submodules folders.

*<span style="color:green">Added in version 1.2.0</span>*

(workspaceSubProjects)=
### **`workspaceSubProjects`** -- full subprojects list

| Type | Default value |
|-     |-
| list[str]  | Generated by {py:class}`nmk_workspace.resolvers.SubProjectsResolver`

This is the recursive list of all founds relative nmk subprojects folders (i.e. all subfolders that both are a git submodule and contains a **nmk.yml** file).

## Subprojects building

This configuration items are used to parameterize how workspace subprojects are built.

(workspaceSubProjectsToBuildFirst)=
### **`workspaceSubProjectsToBuildFirst`** -- ordered list of subprojects to build first

| Type | Default value |
|-     |-
| list[str]  | []

This list is used by the subprojects builder to identify which projects need to be built first, and in which order. Subprojects path are provided relatively to
the workspace root.

```{note}
Projects in this list that are not referenced in {ref}`${workspaceSubProjectsToBuild}<workspaceSubProjectsToBuild>` will be ignored.

*<span style="color:orange">Behavior changed in version 1.1.0</span>*
```

(workspaceSubProjectsToBuild)=
### **`workspaceSubProjectsToBuild`** -- list of subprojects to build

| Type | Default value |
|-     |-
| list[str]  | {ref}`${workspaceSubProjects}<workspaceSubProjects>`

This list is used by the subprojects builder to identify all projects that need to be built.
Projects in this list will be built after the {ref}`${workspaceSubProjectsToBuildFirst}<workspaceSubProjectsToBuildFirst>` ones, and before the {ref}`${workspaceSubProjectsToBuildAfter}<workspaceSubProjectsToBuildAfter>` ones. Subprojects path are provided relatively to the workspace root.

```{note}
Projects in this list that are also referenced in {ref}`${workspaceSubProjectsToBuildAfter}<workspaceSubProjectsToBuildAfter>` will be automatically ignored.
```

(workspaceSubProjectsToBuildAfter)=
### **`workspaceSubProjectsToBuildAfter`** -- ordered list of subprojects to build after all the others

| Type | Default value |
|-     |-
| list[str]  | []

This list is used by the subprojects builder to identify which projects need to be built after all the other ones, and in which order. Subprojects path are provided relatively to
the workspace root.

```{note}
Projects in this list that are not referenced in {ref}`${workspaceSubProjectsToBuild}<workspaceSubProjectsToBuild>` will be ignored.

*<span style="color:orange">Behavior changed in version 1.1.0</span>*
```

(workspaceSubProjectsToExclude)=
### **`workspaceSubProjectsToExclude`** -- list of subprojects patterns to be ignored

| Type | Default value |
|-     |-
| list[str]  | []

When iterating over projects to be built, the subprojects builder will ignore ones matching with any of the patterns ([fnmatch-style](https://docs.python.org/library/fnmatch.html)) provided in this list.

(workspaceBuildExtraArgs)=
### **`workspaceBuildExtraArgs`** -- nmk command extra args for subprojects build

| Type | Default value |
|-     |-
| str  | ""

This string will be appended to the **`nmk`** command used to build subprojects. E.g. this can be usefull to ignore specific tasks.

(workspaceBuildExtraArgsByStage)=
### **`workspaceBuildExtraArgsByStage`** -- nmk command extra args for subprojects build

| Type | Default value |
|-     |-
| str  | "" for all commands

This string will be appended to the **`nmk`** command used to build subprojects, specifically for each metacommand defined by this plugin.

*<span style="color:green">Added in version 1.1.0</span>*

(workspaceBuildEnabled)=
### **`workspaceBuildEnabled`** -- meta-commands enablement for subprojects build

| Type | Default value |
|-     |-
| dict[str, bool]  | true for all commands

This dict allows to enable/disable different metacommands defined by this plugin.

(workspaceBuildIgnoreFailures)=
### **`workspaceBuildIgnoreFailures`** -- failures ignore options for subprojects build

| Type | Default value |
|-     |-
| dict[str, bool]  | false for all commands, except for "tests"

This dict allows to tell builder to ignore any failures occurring when building a subproject.

(workspaceDisableLocalTasks)=
### **`workspaceDisableLocalTasks`** -- local build disablement for subprojects build

| Type | Default value |
|-     |-
| bool | [**`${isLocalBuild}`**](https://nmk-base.readthedocs.io/en/stable/config.html#islocalbuild)

This item disables all subprojects builds if the project is built locally (no effect in CI).

*<span style="color:green">Added in version 1.2.0</span>*