2017-11-26 16:36:46 -05:00
Build and Install KeePassXC
2016-10-26 08:19:28 -04:00
=================
2017-11-26 16:36:46 -05:00
This document will guide you through the steps to build and install KeePassXC from source.
You can visit the online version of this document at the following link:
2016-10-26 08:19:28 -04:00
https://github.com/keepassxreboot/keepassx/wiki/Install-Instruction-from-Source
2017-12-12 03:15:23 -05:00
The [KeePassXC QuickStart ](./docs/QUICKSTART.md ) gets you started using KeePassXC on your
2017-11-26 16:36:46 -05:00
Windows, Mac, or Linux computer using the pre-built binaries.
2016-10-26 08:19:28 -04:00
Build Dependencies
==================
The following tools must exist within your PATH:
* make
* cmake (>= 2.8.12)
* g++ (>= 4.7) or clang++ (>= 3.0)
The following libraries are required:
* Qt 5 (>= 5.2): qtbase and qttools5
* libgcrypt (>= 1.6)
* zlib
* libmicrohttpd
* libxi, libxtst, qtx11extras (optional for auto-type on X11)
2017-12-12 03:15:23 -05:00
* libsodium (>= 1.0.12, optional for keepassxc-browser support)
2018-01-01 13:21:02 -05:00
* libargon2
2016-10-26 08:19:28 -04:00
Prepare the Building Environment
================================
2017-11-26 16:36:46 -05:00
* [Building Environment on Linux ](https://github.com/keepassxreboot/keepassxc/wiki/Set-up-Build-Environment-on-Linux )
* [Building Environment on Windows ](https://github.com/keepassxreboot/keepassxc/wiki/Set-up-Build-Environment-on-Windows )
* [Building Environment on MacOS ](https://github.com/keepassxreboot/keepassxc/wiki/Set-up-Build-Environment-on-OS-X )
2016-10-26 08:19:28 -04:00
Build Steps
===========
To compile from source, open a **Terminal (on Linux/MacOS)** or a **MSYS2-MinGW shell (on Windows)** < br />
**Note:** on Windows make sure you are using a **MINGW shell** by checking the label before the current path
2017-12-12 03:15:23 -05:00
First, download the KeePassXC [source tarball ](https://keepassxc.org/download#source )
2017-11-26 16:36:46 -05:00
or check out the latest version from our [Git repository ](https://github.com/keepassxreboot/keepassxc ).
To clone the project from Git, `cd` to a suitable location and run
```bash
git clone https://github.com/keepassxreboot/keepassxc.git
```
This will clone the entire contents of the repository and check out the current `develop` branch.
To update the project from within the project's folder, you can run the following command:
```bash
git pull
```
Navigate to the directory where you have downloaded KeePassXC and type these commands:
2016-10-26 08:19:28 -04:00
```
2017-11-26 16:36:46 -05:00
cd directory-where-sources-live
2011-12-29 17:24:01 -05:00
mkdir build
cd build
2017-11-26 16:36:46 -05:00
cmake -DWITH_TESTS=OFF ...and other options - see below...
2016-10-26 08:19:28 -04:00
make
```
2017-12-12 03:15:23 -05:00
These steps place the compiled KeePassXC binary inside the `./build/src/` directory.
2017-11-26 16:36:46 -05:00
(Note the cmake notes/options below.)
2016-10-26 08:19:28 -04:00
2017-12-12 03:15:23 -05:00
**Cmake Notes:**
2011-12-29 17:24:01 -05:00
2017-11-26 16:36:46 -05:00
* Common cmake parameters
2016-10-26 08:19:28 -04:00
2017-11-26 16:36:46 -05:00
```
-DCMAKE_INSTALL_PREFIX=/usr/local
-DCMAKE_VERBOSE_MAKEFILE=ON
-DCMAKE_BUILD_TYPE=< RelWithDebInfo / Debug / Release >
-DWITH_GUI_TESTS=ON
```
* cmake accepts the following options:
```
-DWITH_XC_AUTOTYPE=[ON|OFF] Enable/Disable Auto-Type (default: ON)
-DWITH_XC_HTTP=[ON|OFF] Enable/Disable KeePassHTTP and custom icon downloads (default: OFF)
-DWITH_XC_YUBIKEY=[ON|OFF] Enable/Disable YubiKey HMAC-SHA1 authentication support (default: OFF)
2017-12-12 03:15:23 -05:00
-DWITH_XC_BROWSER=[ON|OFF] Enable/Disable keepassxc-browser extension support (default: OFF)
2017-11-26 16:36:46 -05:00
-DWITH_TESTS=[ON|OFF] Enable/Disable building of unit tests (default: ON)
-DWITH_GUI_TESTS=[ON|OFF] Enable/Disable building of GUI tests (default: OFF)
-DWITH_DEV_BUILD=[ON|OFF] Enable/Disable deprecated method warnings (default: OFF)
-DWITH_ASAN=[ON|OFF] Enable/Disable address sanitizer checks (Linux / macOS only) (default: OFF)
-DWITH_COVERAGE=[ON|OFF] Enable/Disable coverage tests (GCC only) (default: OFF)
```
* If you are on MacOS you must add this parameter to **Cmake** , with the Qt version you have installed< br /> `-DCMAKE_PREFIX_PATH=/usr/local/Cellar/qt5/5.6.2/lib/cmake/`
2012-04-25 14:22:44 -04:00
2017-11-26 16:36:46 -05:00
:exclamation: When building with ASan support on macOS, you need to use `export ASAN_OPTIONS=detect_leaks=0` before running the tests (no LSan support in macOS).
2011-12-29 17:24:01 -05:00
2016-10-26 08:19:28 -04:00
Installation
============
2017-11-26 16:36:46 -05:00
After you have successfully built KeePassXC, install the binary by executing the following:
2016-10-26 08:19:28 -04:00
```bash
sudo make install
```
You can specify the destination dir with
```
DESTDIR=X
```
Packaging
=========
2017-01-04 18:47:29 -05:00
You can create a package to redistribute KeePassXC (zip, deb, rpm, dmg, etc..)
2016-10-26 08:19:28 -04:00
```
2013-11-30 06:49:29 -05:00
make package
2016-10-26 08:19:28 -04:00
```
Testing
=======
2013-11-30 06:49:29 -05:00
2016-10-26 08:19:28 -04:00
You can perform test on the executable
```
make test
```
2012-05-28 06:11:44 -04:00
2016-10-26 08:19:28 -04:00
Common parameters:
```
CTEST_OUTPUT_ON_FAILURE=1
ARGS+=-jX
ARGS+="-E testgui"
```