»Home
»News
»Download
»Documentation
     »oathtool(1)
     »pskctool(1)
     »Liboath API
     »PSKC Tutorial
     »Libpskc API
     »pam_oath
»Contribute
OATH Toolkit
One-time password components

# OATH Toolkit Developer Information

Download, build and self-check version controlled sources:

``` git clone https://codeberg.org/oath-toolkit/oath-toolkit.git cd oath-toolkit ./bootstrap ./configure make make check ```

Links to resources that may be useful if you want to get involved the project:

# Dependencies

We rely on several tools to build the software, including:

The software is typically distributed with your operating system, and the instructions for installing them differ. Below are some hints. If you have hints on how to install the required dependencies on other operating systems, please provide a patch explaining it. Find inspiration from build rules in .gitlab-ci.yml.

## Debian/Ubuntu dependencies

``` apt-get install make git autoconf automake libtool bison gengetopt valgrind apt-get install libpam0g-dev libxmlsec1-dev libxml2-utils apt-get install gnulib help2man gtk-doc-tools libglib2.0-dev dblatex ```

# Valgrind suppression

When building from version controlled sources, some developer specific flags are automatically enabled. For example, the self-checks are run under valgrind if available. For various reasons, you may run into valgrind false positives that will cause self-checks to fail. First be sure to install debug symbols for system libraries. We ship a Valgrind suppression file to address common issues. You can use it by putting the following in your ~/.valgrindrc:

``` --suppressions=/path/to/oath-toolkit/libpskc/tests/libpskc.supp ```

# Release Process

To prepare a release you need some additional tools:

Debian/Ubuntu dependencies:

``` apt-get install groff asciidoc xsltproc lcov clang rsync ```

Most of the release process rely on gnulib scripts and maint.mk rules, and the steps below are inspired by gnulib’s README-release.

Here are most of the steps we (maintainers) follow when making a release.

  • Start from a clean, up-to-date git directory on "main":

``` git checkout main git pull origin main git clean -d -x -f git restore --staged . git reset --hard ```

  • Ensure that the latest stable versions of autoconf, automake, etc. are in your PATH.

  • Make sure you have updated to latest gnulib files. The GitLab CI/CD pipeline uses the GNULIB_REVISION setting from .gitlab-ci.yml, and you ought to use the same locally to be able to reproduce the release tarball.

  • Make sure NEWS reflect all changes made since the last release.

``` make review-diff ```

  • Ensure that you have no uncommitted diffs. This should produce no output:

``` git diff ```

  • Ensure that you’ve pushed all changes that belong in the release:

``` git push origin main ```

  • Check that the GitLab CI/CD Pipeline is reporting all is well:

https://gitlab.com/oath-toolkit/oath-toolkit/-/pipelines

  • Run the following commands:

``` ./bootstrap ./configure make check syntax-check distcheck ```

  • To (i) set the date, version number, and release TYPE on line 3 of NEWS, (ii) commit that, and (iii) tag the release, run

``` # "TYPE" must be stable, beta or alpha make release-commit RELEASE=X.Y.Z TYPE ```

  • Push the NEWS-updating changes and the new tag:

``` v=$(cat .prev-version) git push origin main tag v$v ```

  • Run the following to create release tarballs.

``` make release RELEASE=X.Y.Z TYPE gnulib_dir=../gnulib ```

  • Write the release announcement that you will soon post. Start with the template, $HOME/announce-oath-toolkit-X.Y.Z that was just created by that "make" command.

  • Confirm that the pipeline passes and that your local tarballs are bit-by-bit identical to the B-Guix and R-Guix pipeline jobs.

  • To upload the tarballs to the Savannah download area run:

``` make release-upload-ftp ```

  • Make sure ../www-oath-toolkit/ contains a git checkout of the website git repository.

``` cd .. git clone ssh://git@codeberg.org/oath-toolkit/pages.git www-oath-toolkit ```

  • Run the following to upload the website:

``` make release-upload-www ```

  • Send the announcement email message.

  • Start next development cycle by pushing the post-release commit.

``` git push main ```

  • Commit and push updates of the release process depending on your experience following these steps.

Happy hacking!