== Building and developing Yubico Authenticator
This document describes how to build and package Yubico Authenticator from
source.

NOTE: Yubico Authenticator 6 uses a new codebase built using the Flutter
framework. The previous Qt codebase can be found in the `legacy` branch.

=== Requirements
You will need the Flutter SDK with enabled desktop support, see:
https://flutter.dev/desktop

Development has been done using the "Install from git" method of installing the
SDK, from the "stable" channel.

=== Dependencies
This project uses several dependencies specified in the pubspec.yaml file, as
well as in the helper/pyproject.toml file. These files specify version ranges
which should be compatible. The corresponding pubspec.lock and
helper/poetry.lock files contain the exact versions which are currently being
used when building the app.

==== Versioning (important for package maintainers!)
We recommend that this application be bundled with all its dependencies, using
the exact versions specified in the lock files. If this approach isn't viable,
we strongly urge that upper bounds be set on the dependencies in accordance
with the pubspec and pyproject files. For example, the current version depends
on `yubikey-manager >=5, <6`. It will likely not work with versions outside
this range!

=== Building the Yubico Authenticator Helper
The GUI requires a compiled version of Helper to run, which is built from the
sources in helper/ in this repository. Requirements for all platforms are
Python >= 3.8 and Poetry. This needs to be built prior to running
`flutter build` or `flutter run`.

==== Windows

Make sure the http://www.swig.org/[swig] executable is in your PATH.

==== macOS

    $ brew install swig

==== Linux (Debian-based distributions)

    $ sudo apt install swig libu2f-udev pcscd libpcsclite-dev

==== Linux (RPM-based distributions)

    # Tested on Fedora 34
    $ sudo dnf install pcsc-lite-devel python3-devel swig

When prerequisites are installed you build the helper by running `build-helper.sh`
(or `build-helper.bat` on Windows).

NOTE: You will need to re-run the build script if changes have been made to
Helper's code, or if `flutter clean` has been run.

=== Running the app
Before you can build or run the app using the flutter command you need to build
the helper, as described in the previous section!

To start the app, run:

  flutter run -d <os>

where <os> is "windows", "macos", "linux", or an attached Android device name.
use `flutter devices` to list available devices.

You can add the `--release` flag to run a release build instead of debug.

=== Building the app
To build the app without running it, use:

  flutter build <os>

where <os> is "windows", "macos", "linux", or "apk".
Builds of the app will be create under `build/<os>/` for desktop, or
`build/app/` for Android.

=== Running tests
This project uses both unit tests and integration tests.

The unit tests can be run with the command:

  flutter test

These do not require a YubiKey, and are relatively quick to run.

The integration tests are slower but cover more end-to-end functionality. The
require an attached YubiKey to run, and will make modifications to the data
stored on that YubiKey. For instructions on running these tests, see
link:../integration_test/testdoc.adoc[these instructions].


=== Packaging for MacOS
See link:MacOS_Packaging.adoc[MacOS Packaging].