Tasks

The nmk-base plugin defines the tasks described below.

Meta tasks

This plugin defines some meta tasks that can be used by other plugins as kind of build “phases”

`setup` task

The setup task aims to be the first phase of the build, allowing to perform prebuild operations like code generation, code formatting, dependencies checking, etc…

`build` task

The build task shall be used to perform all operation that build temporary and/or artifact files for the current project.

It is the default build task (i.e. this is the built task when nmk is invoked without argument).

It depends on the setup task.

`tests` task

The tests task shall be used to perform all automated testing operations on generated software.

It depends on the build task.

`publish` task

The publish task shall be used to publish built artifacts where they should be stored, as decided by the project.

It depends on the build task.

Cleaning tasks

`clean` – output cleaning

The clean task will simply remove the ${outputDir} folder and its entire content.

Usage example:

$ nmk clean
2022-02-20 14:37:54 (I) [clean] 🧹 - Clean build output
2022-02-20 14:37:54 (I) nmk 🏁 - Done

`git.clean` – full clean

The git.clean task will use git to clean the project folder, i.e. by removing all git ignored files.

Warning: this will remove (at least) both the venv and .nmk folders. Consequently, the build will immediately stop after this task, ignoring other tasks eventually specified on the command line. After this task is executed, the buildenv loading scripts will have to be used again to setup the project and reinstall nmk

Helper tasks

`version` – display version

Property	Value/description
builder	`nmk_base.helpers.VersionBuilder`

The version task will list the versions of nmk itself, plus all plugin versions contributed to ${nmkPluginsVersions} object.

Example:

$ nmk version
2022-02-20 14:37:02 (I) [version] 🏷  - Display used nmk + plugins versions
2022-02-20 14:37:02 (I) [version] 🏷  -  👉 nmk: 0.0.0.post37+gf907587
2022-02-20 14:37:02 (I) [version] 🏷  -  👉 base: 1.0.0
2022-02-20 14:37:02 (I) nmk 🏁 - Done

`help` – display help links

Property	Value/description
builder	`nmk_base.helpers.HelpBuilder`

The help task will list the help page URL of nmk itself, plus all plugin pages URLs contributed to ${nmkPluginsDocs} object.

Example:

$ nmk help
2022-02-20 14:42:24 (I) [help] 🆘 - Display online help links
2022-02-20 14:42:24 (I) [help] 🆘 -  👉 nmk: https://github.com/dynod/nmk/wiki
2022-02-20 14:42:24 (I) [help] 🆘 -  👉 base: https://github.com/dynod/nmk/wiki/nmk-base-plugin
2022-02-20 14:42:24 (I) nmk 🏁 - Done

`tasks` – list known tasks

Property	Value/description
builder	`nmk_base.helpers.TaskListBuilder`

The tasks task will list all the known tasks for the built project.

Example:

$ nmk tasks
2022-02-20 14:43:18 (I) [tasks] 🗃 - List all available tasks
2022-02-20 14:43:18 (I) [tasks] 🧹 -  👉 clean: Clean build output
2022-02-20 14:43:18 (I) [tasks] 🛫 -  👉 setup: Setup project configuration
2022-02-20 14:43:18 (I) [tasks] 🛠 -  👉 build: Build project artifacts
2022-02-20 14:43:18 (I) [tasks] 🤞 -  👉 tests: Run automated tests
2022-02-20 14:43:18 (I) [tasks] 🏷 -  👉 version: Display used nmk + plugins versions
2022-02-20 14:43:18 (I) [tasks] 🆘 -  👉 help: Display online help links
2022-02-20 14:43:18 (I) [tasks] 🗃 -  👉 tasks: List all available tasks

...

2022-02-20 14:42:24 (I) nmk 🏁 - Done

Setup tasks

All tasks in this chapter are dependencies of the main setup task.

`buildenv` – buildenv loading scripts generation

Property	Value/description
builder	`nmk_base.buildenv.BuildenvInitBuilder`
input	${venvState} file
output	buildenv loading scripts

The buildenv task updates buildenv loading scripts, aiming to be persisted in project repository, and allowing to:

create a local python venv where nmk (and all python dependencies of the project) will be installed
enable this venv

`git.version` – git version update

Property	Value/description
builder	`nmk_base.git.GitVersionRefresh`
output	${gitVersionStamp} file
deps	out task

This task is used to update the ${gitVersionStamp} file, each time the ${gitVersion} value is updated (new commit, new tag…)

`git.ignore` – generate .gitignore file

Property	Value/description
builder	`nmk_base.git.GitIgnore`
input	${gitIgnore} & ${gitIgnoreTemplate} files
output	${gitIgnore} & ${gitIgnoreStamp} files
deps	out task

This task is used to update the ${gitIgnore} file with a fragment generated from the list of ignored files configured in ${gitIgnoredFiles} item.

Notes:

Project-relative paths are automatically made relative to project root.
Non project-relative absolute paths are ignored when generating the fragment.

`git.attributes` – generate .gitattributes file

Property	Value/description
builder	`nmk_base.git.GitAttributes`
output	${gitAttributes} & ${gitAttributesStamp} files
deps	out task

This task is used to update the ${gitAttributes} file with a fragment generated from the following config items:

${linuxLineEndings}: list of file extensions (“.xxx” format) requiring to be systematically handled with Linux line endings
${windowsLineEndings}: list of file extensions (“.xxx” format) requiring to be systematically handled with Windows line endings

`py.req` – generate python venv requirements file

Property	Value/description
builder	`nmk_base.common.TemplateBuilder`
input	${venvArchiveDeps} & ${venvFileDeps} & ${venvRequirementsTemplate} files
output	${PROJECTDIR}/${venvRequirements} file

This task merges all python venv requirements in one single generated file (${venvRequirements}). This file is used:

by “buildenv” loading scripts to bootstrap the project just after the clone
by py.venv task to update the venv when requirements change during the project lifecycle

It is triggered only if:

one of referenced requirement files (from ${venvFileDeps} config list) is updated
one of referenced archive files (from ${venvArchiveDeps} config list) is updated
the requirements template (from ${venvRequirementsTemplate} config list) is updated
project files are updated

`py.venv` – update python venv

Property	Value/description
builder	`nmk_base.venv.VenvUpdateBuilder`
input	${PROJECTDIR}/${venvRequirements} file
output	${ROOTDIR}/${venvName} & ${venvState} files
deps	out & py.req tasks

This task updates the Python venv from the expected requirements, as soon as they are updated (i.e. when ${venvRequirements} file changes).

It also generates a dump (${venvState}) of all installed packages (using the pip requirement specifiers syntax); this dump can be used to compare builds, and/or to restore a previous build exact venv environment (from troubleshooting or others…)

`out` – output folder creation

Property	Value/description
builder	`nmk_base.common.MkdirBuilder`
output	${outputDir} folder

This task simply silently creates the ${outputDir} folder. All tasks aiming to create files in this folder should reference this task.

Test tasks

All tasks in this chapter are dependencies of the main tests task.

`git.dirty` – check for dirty project folder

Property	Value/description
builder	`nmk_base.git.GitIsDirty`
if	${gitEnableDirtyCheck} folder

This task verifies if project folder is dirty (e.g. contains not committed files). In this case, it makes the build failing.

Tasks

Meta tasks

setup task

build task

tests task

publish task

Cleaning tasks

clean – output cleaning

git.clean – full clean

Helper tasks

version – display version

help – display help links

tasks – list known tasks

Setup tasks

buildenv – buildenv loading scripts generation

git.version – git version update

git.ignore – generate .gitignore file

git.attributes – generate .gitattributes file

py.req – generate python venv requirements file

py.venv – update python venv

out – output folder creation

Test tasks

git.dirty – check for dirty project folder

`setup` task

`build` task

`tests` task

`publish` task

`clean` – output cleaning

`git.clean` – full clean

`version` – display version

`help` – display help links

`tasks` – list known tasks

`buildenv` – buildenv loading scripts generation

`git.version` – git version update

`git.ignore` – generate .gitignore file

`git.attributes` – generate .gitattributes file

`py.req` – generate python venv requirements file

`py.venv` – update python venv

`out` – output folder creation

`git.dirty` – check for dirty project folder