# 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://github.com/dynod/nmk/wiki/nmk-base-plugin"}

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

## 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>`" ]

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 | Generated 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] | [ "nmk" ]

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       | "venv"

Name of the python venv folder.

(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.

## 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
```