Mage #

Vikunja uses Mage to script common development tasks and even releasing. Mage is a pure go solution which allows for greater flexibility and things like better paralelization.

This document explains what taks are available and what they do.

Installation #

To use mage, you’ll need to install the mage cli. To install it, run the following command:

go install github.com/magefile/mage

Categories #

There are multiple categories of subcommands in the magefile:

  • build: Contains commands to build a single binary
  • check: Contains commands to statically check the source code
  • release: Contains commands to release Vikunja with everything that’s required
  • test: Contains commands to run all kinds of tests
  • dev: Contains commands to run development tasks
  • misc: Commands which do not belong in either of the other categories

CI #

These tasks are automatically run in our CI every time someone pushes to master or you update a pull request:

  • mage check:lint
  • mage check:fmt
  • mage check:ineffassign
  • mage check:misspell
  • mage check:goconst
  • mage build:generate
  • mage build:build

Build #

Build Vikunja #

mage build:build

Builds a vikunja-binary in the root directory of the repo for the platform it is run on.

Statically compile all templates into the binary #

mage build:generate

This generates static code with all templates, meaning no template need to be referenced at runtime.

clean #

mage build:clean

Cleans all build, executable and bindata files

Check #

All check sub-commands exit with a status code of 1 if the check fails.

Various code-checks are available:

  • mage check:all: Runs fmt-check, lint, got-swag, misspell-check, ineffasign-check, gocyclo-check, static-check, gosec-check, goconst-check all in parallel
  • mage check:fmt: Checks if the code is properly formatted with go fmt
  • mage check:go-sec: Checks the source code for potential security issues by scanning the Go AST using the gosec tool
  • mage check:goconst: Checks for repeated strings that could be replaced by a constant using goconst
  • mage check:gocyclo: Checks for the cyclomatic complexity of the source code using gocyclo
  • mage check:got-swag: Checks if the swagger docs need to be re-generated from the code annotations
  • mage check:ineffassign: Checks the source code for ineffectual assigns using ineffassign
  • mage check:lint: Runs golint on all packages
  • mage check:misspell: Checks the source code for misspellings
  • mage check:static: Statically analyzes the source code about a range of different problems using staticcheck

Release #

Build Releases #

mage release

Builds binaries for all platforms and zips them with a copy of the templates/ folder. All built zip files are stored into dist/zips/. Binaries are stored in dist/binaries/, binaries bundled with templates are stored in dist/releases/.

All cross-platform binaries built using this series of commands are built with the help of xgo. The mage command will automatically install the binary to be able to use it.

mage release:release is a shortcut to execute mage release:dirs release:windows release:linux release:darwin release:copy release:check release:os-package release:zip.

  • mage release:dirs creates all directories needed
  • mage release:windows/release:linux/release:darwin execute xgo to build for their respective platforms
  • mage release:copy bundles binaries with a copy of the LICENSE and sample config files to then be zipped
  • mage release:check creates sha256 checksums for each binary which will be included in the zip file
  • mage release:os-package bundles a binary with the sha256 checksum file, a sample config.yml and a copy of the license in a folder for each architecture
  • mage release:compress compresses all build binaries with upx to save space
  • mage release:zip paclages a zip file for the files created by release:os-package

Build os packages #

mage release:packages

Will build .deb, .rpm and .apk packages to dist/os-packages.

Make a debian repo #

mage release:reprepro

Takes an already built debian package and creates a debian repo structure around it.

Used to be run inside a docker container in the CI process when releasing.

Test #

unit #

mage test:unit

Runs all tests except integration tests.

coverage #

mage test:coverage

Runs all tests except integration tests and generates a coverage.html file to inspect the code coverage.

integration #

mage test:integration

Runs all integration tests.

Dev #

Create a new migration #

mage dev:create-migration

Creates a new migration with the current date. Will ask for the name of the struct you want to create a migration for.

Misc #

Format the code #

mage fmt

Formats all source code using go fmt.

Generate swagger definitions from code comments #

mage do-the-swag

Generates swagger definitions from the comment annotations in the code.