# Configuration Reference

The **`nmk-base`** 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 projet if you need to fine tune the plugin behavior. [Some items](extend.md) are specifically designed to be extended by **`nmk`** projects and plugins.

---

## Paths and files

---

### **`sourceDir`** -- source base directory

| Type | Default value     |
| ---- | ----------------- |
| str  | ${PROJECTDIR}/src |

Main source directory for the project (containing source files; used by other plugins).

---

(outputDir)=

### **`outputDir`** -- output base directory

| Type | Default value     |
| ---- | ----------------- |
| str  | ${PROJECTDIR}/out |

Output folder used to generate build artifacts, temporary files, tools reports, etc...

---

## Helper contributions

---

(projectName)=

### **`projectName`** -- project name

| Type | Default value |
| ---- | ------------- |
| str  | MyProject     |

Name of the project

---

(projectAuthor)=

### **`projectAuthor`** -- project author

| Type | Default value    |
| ---- | ---------------- |
| str  | "Project Author" |

Author of the project

---

(nmkPluginsVersions)=

### **`nmkPluginsVersions`** -- referenced plugins versions

| Type          | Default value                         |
| ------------- | ------------------------------------- |
| dict[str,str] | {"nmk-base": ${nmkBasePluginVersion}} |

Plugins versions, indexed by names, to be displayed by **{ref}`version<version>`** task

---

(nmkPluginsDocs)=

### **`nmkPluginsDocs`** -- referenced plugins help pages

| Type          | Default value                                    |
| ------------- | ------------------------------------------------ |
| dict[str,str] | {"nmk-base": "https://nmk-base.readthedocs.io/"} |

Plugins help pages URLs indexed by names, to be displayed by **{ref}`help<help>`** task.

---

(requestFunction)=

### **`requestFunction`** -- request function for download tasks

| Type | Default value |
| ---- | ------------- |
| str  | requests.get  |

Canonical path to a requests-like function, that should be passed as **request_function** parameter for {py:class}`nmk_base.common.DownloadBuilder` based
download tasks. The specified function must behave like **`requests.get`** function (same input/output parameters).

_<span style="color:green">Added in version 1.3.0</span>_

## Git

The **`nmk-base`** plugin handles some git related configuration items, listed in this chapter.

---

(gitVersion)=

### **`gitVersion`** -- git version

| Type | Default value                                            |
| ---- | -------------------------------------------------------- |
| str  | Generated by {py:class}`nmk_base.git.GitVersionResolver` |

Version read from git for the current project, using **`git describe --tags --dirty`** command.

---

(gitVersionStamp)=

### **`gitVersionStamp`** -- git version resolution stamp file

| Type | Default value                              |
| ---- | ------------------------------------------ |
| str  | {ref}`${outputDir}<outputDir>`/.gitversion |

Get version stamp file, updated by **{ref}`git.version<git.version>`** task each time {ref}`${gitVersion}<gitVersion>` value changes. Can be used as input by tasks expecting to be triggered when git version changes.

---

(gitIgnore)=

### **`gitIgnore`** -- generated .gitignore file

| Type | Default value              |
| ---- | -------------------------- |
| str  | "${PROJECTDIR}/.gitignore" |

Target generated **`.gitignore`** file.

---

(gitIgnoreTemplate)=

### **`gitIgnoreTemplate`** -- .gitignore template file

| Type | Default value                    |
| ---- | -------------------------------- |
| str  | "${BASEDIR}/templates/gitignore" |

Template used by **{ref}`git.ignore<git.ignore>`** task to generate **`.gitignore`** fragment.

---

(gitIgnoreStamp)=

### **`gitIgnoreStamp`** -- .gitignore generated stamp file

| Type | Default value                             |
| ---- | ----------------------------------------- |
| str  | {ref}`${outputDir}<outputDir>`/.gitignore |

Stamp file for generated **`.gitignore`** fragment.

---

(gitIgnoredFiles)=

### **`gitIgnoredFiles`** -- git ignored files list

| Type      | Default value                                                                                                                          |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| list[str] | [ "${PROJECTDIR_NMK}/", "{ref}`${outputDir}<outputDir>`", "{ref}`${venvName}<venvName>`", "{ref}`${buildenvFolder}<buildenvFolder>`" ] |

List of files/folders to be added when generating **`.gitignore`** file.

---

(gitAttributes)=

### **`gitAttributes`** -- generated .gitattributes file

| Type | Default value                  |
| ---- | ------------------------------ |
| str  | "${PROJECTDIR}/.gitattributes" |

Target generated **`.gitattributes`** file.

---

(gitAttributesTemplate)=

### **`gitAttributesTemplate`** -- .gitattributes template file

| Type | Default value                        |
| ---- | ------------------------------------ |
| str  | "${BASEDIR}/templates/gitattributes" |

Template used by **{ref}`git.attributes<git.attributes>`** task to generate **`.gitattributes`** fragment.

---

(gitAttributesStamp)=

### **`gitAttributesStamp`** -- .gitattributes generated stamp file

| Type | Default value                                 |
| ---- | --------------------------------------------- |
| str  | {ref}`${outputDir}<outputDir>`/.gitattributes |

Stamp file for generated **`.gitattributes`** fragment.

---

(linuxLineEndings)=

### **`linuxLineEndings`** -- files with Linux line endings

| Type      | Default value |
| --------- | ------------- |
| list[str] | [ ".sh" ]     |

List of files extensions (".xxx" format) with Linux line endings; will be declared with "**text eol=lf**" attribute in generated **`.gitattributes`** fragment.

---

(windowsLineEndings)=

### **`windowsLineEndings`** -- files with Windows line endings

| Type      | Default value      |
| --------- | ------------------ |
| list[str] | [ ".bat", ".cmd" ] |

List of files extensions (".xxx" format) with Windows line endings; will be declared with "**text eol=crlf**" attribute in generated **`.gitattributes`** fragment.

---

(gitEnableDirtyCheck)=

### **`gitEnableDirtyCheck`** -- enable git dirty folder check

| Type | Default value                                                                                                                                                                      |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| bool | {ref}`${isCIBuild}<isCIBuild>`<br> <br>_<span style="color:orange">Changed in version 1.1.0</span>_ -- Previous value was directly resolved by {py:class}`nmk_base.git.CIResolver` |

Enablement flag for **{ref}`git.dirty<git.dirty>`** task (by default, returns True if the **CI** environment variable is defined).

## Python venv

---

(venvPkgDeps)=

### **`venvPkgDeps`** -- venv packages dependencies list

| Type      | Default value                                                                                                                                                                                         |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| list[str] | **[${PACKAGESREFS}](https://nmk.readthedocs.io/en/stable/file.html#built-in-config-items)**<br> <br>_<span style="color:orange">Changed in version 1.0.1</span>_ -- Previous value was `["nmk-base"]` |

List of python packages references to be installed in python venv (using [pip requirement specifiers syntax](https://pip.pypa.io/en/stable/reference/requirement-specifiers/)).

---

(venvArchiveDeps)=

### **`venvArchiveDeps`** -- venv archives dependencies list

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

List of local python module archive paths to be installed in python venv.

---

(venvFileDeps)=

### **`venvFileDeps`** -- venv requirement files list

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

List of pip requirement files to be installed in python venv.

---

(venvName)=

### **`venvName`** -- venv name

| Type | Default value                                                                                                                                                       |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| str  | Resolved by {py:class}`nmk_base.backends.VenvNameResolver`<br> <br>_<span style="color:orange">Changed in version 1.2.0</span>_<br>Previous static value was "venv" |

Name of the python venv folder, depending on the current environment backend (may be "venv" or ".venv").

---

(venvRoot)=

### **`venvRoot`** -- venv root folder

| Type | Default value                                              |
| ---- | ---------------------------------------------------------- |
| str  | Resolved by {py:class}`nmk_base.backends.VenvRootResolver` |

Root python venv folder, depending on the current environment backend (may be a project subfolder, a parent project subfolder or a temporary folder).

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

---

(venvRequirements)=

### **`venvRequirements`** -- generated requirements file name

| Type | Default value      |
| ---- | ------------------ |
| str  | "requirements.txt" |

Name of the generated merged requirements file for python venv (relative to **`${PROJECTDIR}`**).

---

(venvState)=

### **`venvState`** -- output requirements file name

| Type | Default value                                     |
| ---- | ------------------------------------------------- |
| str  | "{ref}`${outputDir}<outputDir>`/requirements.txt" |

Name of the generated requirements file, containing a dump off all installed package versions in python venv.

---

(venvRequirementsTemplate)=

### **`venvRequirementsTemplate`** -- generated requirements file template

| Type | Default value                           |
| ---- | --------------------------------------- |
| str  | "${BASEDIR}/templates/requirements.txt" |

Template used to generate {ref}`${venvRequirements}<venvRequirements>` merged requirements file.

---

(venvBin)=

### **`venvBin`** -- venv executables folder

| Type | Default value                                             |
| ---- | --------------------------------------------------------- |
| str  | Generated by {py:class}`nmk_base.venvbuilder.BinResolver` |

Path of the executables installed in current project venv.

---

(venvPython)=

### **`venvPython`** -- venv python executable

| Type | Default value                                             |
| ---- | --------------------------------------------------------- |
| str  | Generated by {py:class}`nmk_base.venvbuilder.ExeResolver` |

Path of the python executable in current project venv.

---

(venvUpdateInput)=

### **`venvUpdateInput`** -- input file for venv update task

| Type | Default value                                              |
| ---- | ---------------------------------------------------------- |
| str  | ${PROJECTDIR}/{ref}`${venvRequirements}<venvRequirements>` |

Overridable input file pointer for {ref}`py.venv<py.venv>` task.

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

---

(backendUseRequirements)=

### **`backendUseRequirements`** -- is backend using requirements?

| Type | Default value                                                             |
| ---- | ------------------------------------------------------------------------- |
| bool | Generated by {py:class}`nmk_base.backends.BackendUseRequirementsResolver` |

State if current environment backend uses a requirements file or not.

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

---

(backendLegacy)=

### **`backendLegacy`** -- is backend a legacy one?

| Type | Default value                                                    |
| ---- | ---------------------------------------------------------------- |
| bool | Generated by {py:class}`nmk_base.backends.BackendLegacyResolver` |

State if current environment backend is a legacy implementation (i.e. using **`buildenv`** version < 2) or not.

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

---

(buildenvFolder)=

### **`buildenvFolder`** -- legacy buildenv folder

| Type | Default value                                                     |
| ---- | ----------------------------------------------------------------- |
| str  | Generated by {py:class}`nmk_base.backends.BuildenvFolderResolver` |

Gets the folder for legacy buildenv implementation (empty string if using an environment backend version >= 2).

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

---

(buildenvRefresh)=

### **`buildenvRefresh`** -- trigger for legacy buildenv scripts generation

| Type | Default value                                                                                                                                  |
| ---- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| str  | "{ref}`${backendLegacy}<backendLegacy>`"<br> <br>_<span style="color:orange">Changed in version 1.2.0</span>_ Previous static value was `True` |

Enablement condition for **{ref}`buildenv<buildenv>`** task.

---

## System dependencies

---

(systemDeps)=

### **`systemDeps`** -- system dependencies description

| Type                    | Default value                                  |
| ----------------------- | ---------------------------------------------- |
| dict[str,dict[str,str]] | Map of system required commands + instructions |

This maps lists required system commands (dependencies) + install instructions.

Map keys are commands that are expected to be found on the system path.\
Map values are maps containing install instructions, indexed by the install method key:

- if the key is **apt**, the instruction value is a list of apt packages to be installed to provide this command at system level. The corresponding instruction is displayed only if **apt** command is available on the system (e.g. on Ubuntu linux or any other Debian-like Linux distribution).
- if the key is **url**, the instruction value is an URL string, pointing to a web page describing how to install this command.

Example:

```yaml
systemDeps:
  git:
    apt: ["git"]
    url: https://git-scm.com/downloads
```

---

## Build context

---

(isLocalBuild)=

### **`isLocalBuild`** -- is the current build running locally?

| Type | Default value                                    |
| ---- | ------------------------------------------------ |
| bool | Generated by {py:class}`nmk_base.git.CIResolver` |

Checks if the current build is running in local (returns True if the **CI** environment variable is not defined).

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

---

(isCIBuild)=

### **`isCIBuild`** -- is the current build running in CI?

| Type | Default value                                    |
| ---- | ------------------------------------------------ |
| bool | Generated by {py:class}`nmk_base.git.CIResolver` |

Checks if the current build is running in CI (returns True if the **CI** environment variable is defined).

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

---

## Java runtime

Some tools need the **java** runtime to be available; following items help to resolve this command for **nmk** tasks.

---

(javaRuntime)=

### **`javaRuntime`** -- resolved java command path

| Type | Default value                                               |
| ---- | ----------------------------------------------------------- |
| str  | Generated by {py:class}`nmk_base.resolvers.CommandResolver` |

Resolves the **java** command, from provided custom path (in {ref}`${javaRuntimeCustomPath}<javaRuntimeCustomPath>`) or from system path.

```{note}
Resolved path is empty if the command is not found on system path, and if provided custom path is missing or doesn't exist.
```

_<span style="color:green">Added in version 1.3.0</span>_

---

(javaRuntimeCustomPath)=

### **`javaRuntimeCustomPath`** -- java command custom path

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

Provides a custom path for **java** command to be used instead of the system command.

_<span style="color:green">Added in version 1.3.0</span>_