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.
Table of contents
To use mage, you’ll need to install the mage cli. To install it, run the following command:
go install github.com/magefile/mage
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
These tasks are automatically run in our CI every time someone pushes to main or you update a pull request:
Build Vikunja #
vikunja-binary in the root directory of the repo for the platform it is run on.
Statically compile all templates into the binary #
This generates static code with all templates, meaning no template need to be referenced at runtime.
Cleans all build, executable and bindata files
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
Build Releases #
Builds binaries for all platforms and zips them with a copy of the
All built zip files are stored into
dist/zips/. Binaries are stored in
binaries bundled with
templates are stored in
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:dirscreates all directories needed
release:darwinexecute xgo to build for their respective platforms
mage release:copybundles binaries with a copy of the
LICENSEand sample config files to then be zipped
mage release:checkcreates sha256 checksums for each binary which will be included in the zip file
mage release:os-packagebundles a binary with the
sha256checksum file, a sample
config.ymland a copy of the license in a folder for each architecture
mage release:compresscompresses all build binaries with
upxto save space
mage release:zippaclages a zip file for the files created by
Build os packages #
.apk packages to
Make a debian repo #
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.
Runs all tests except integration tests.
Runs all tests except integration tests and generates a
coverage.html file to inspect the code coverage.
Runs all integration tests.
Create a new migration #
Creates a new migration with the current date. Will ask for the name of the struct you want to create a migration for.
Format the code #
Formats all source code using
Generate swagger definitions from code comments #
Generates swagger definitions from the comment annotations in the code.