mirror of
https://github.com/keepassxreboot/keepassxc.git
synced 2025-04-03 20:47:37 +03:00
Update all documentation for 2.7.0
* Update INSTALL.md to align with Wiki * Add sections for new 2.7.0 features including Quick Unlock, Tags, Browser Integration settings, Auto-Type improvements, etc. * Update all documentation images to show new interface details * Expand documentation for database operations
This commit is contained in:
Jonathan White
Janek Bevendorff
parent
9569438295
commit
5c772cea1a
40 changed files with 233 additions and 124 deletions
162
INSTALL.md
162
INSTALL.md
|
|
@ -14,18 +14,19 @@ The following tools must exist within your PATH:
|
|||
* make
|
||||
* cmake (>= 3.3.0)
|
||||
* g++ (>= 4.7) or clang++ (>= 6.0)
|
||||
* asciidoctor
|
||||
* asciidoctor (>= 2.0)
|
||||
|
||||
The following libraries are required:
|
||||
|
||||
* Qt 5 (>= 5.9.5): qtbase5, qtbase5-private, libqt5svg5, qttools5, qt5-image-formats-plugins
|
||||
* botan (>= 2.12)
|
||||
* libargon2
|
||||
* zlib
|
||||
* minizip
|
||||
* readline (for completion in cli)
|
||||
* libqt5x11extras5, libxi, and libxtst (for auto-type on X11)
|
||||
* qtx11extras, libxi, and libxtst (for auto-type on X11)
|
||||
* qrencode
|
||||
* libusb-1.0, pcsclite (optional to support YubiKey on Linux)
|
||||
* libusb-1.0, pcsc-lite (for Yubikey support on Linux)
|
||||
|
||||
Prepare the Building Environment
|
||||
================================
|
||||
|
|
@ -38,110 +39,119 @@ Build Steps
|
|||
===========
|
||||
We recommend using the release tool to perform builds, please read up-to-date instructions [on our wiki](https://github.com/keepassxreboot/keepassxc/wiki/Building-KeePassXC#building-using-the-release-tool).
|
||||
|
||||
To compile from source, open a **Terminal (on Linux/MacOS)** or a **MSYS2-MinGW shell (on Windows)**<br/>
|
||||
**Note:** on Windows you can also use MSVC to build natively, we recommend Visual Studio 2019
|
||||
To compile from source, open a **Terminal (Linux/MacOS)**, the **MSVC Tools Command Prompt (Windows)**, or **MSYS2-MinGW shell (Windows)**. For code development on Windows, you can use Visual Studio 2022, Visual Studio Code, or CLion.
|
||||
|
||||
First, download the KeePassXC [source tarball](https://keepassxc.org/download#source)
|
||||
or check out the latest version from our [Git repository](https://github.com/keepassxreboot/keepassxc).
|
||||
1. Download the KeePassXC [source tarball](https://keepassxc.org/download#source) 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
|
||||
To clone the project from Git, `cd` to a suitable location and run
|
||||
|
||||
```bash
|
||||
git clone https://github.com/keepassxreboot/keepassxc.git
|
||||
```
|
||||
```
|
||||
git clone https://github.com/keepassxreboot/keepassxc.git
|
||||
```
|
||||
|
||||
This will clone the entire contents of the repository and check out the current `develop` branch.
|
||||
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:
|
||||
To update the project from within the project's folder, you can run the following command:
|
||||
|
||||
```bash
|
||||
git pull
|
||||
```
|
||||
```
|
||||
git pull
|
||||
```
|
||||
|
||||
For a stable build, it is recommended to checkout the master branch.
|
||||
For a stable build, it is recommended to check out the master branch.
|
||||
|
||||
```bash
|
||||
git checkout master
|
||||
```
|
||||
```
|
||||
git checkout master
|
||||
```
|
||||
|
||||
NOTE: See the [Windows Build Instructions](https://github.com/keepassxreboot/keepassxc/wiki/Building-KeePassXC#windows) for building with MSVC.
|
||||
2. Navigate to the directory where you have downloaded KeePassXC and type these commands:
|
||||
|
||||
Navigate to the directory where you have downloaded KeePassXC and type these commands:
|
||||
```
|
||||
mkdir build
|
||||
cd build
|
||||
cmake -DWITH_XC_ALL=ON ..
|
||||
make
|
||||
```
|
||||
|
||||
Note: These steps place the compiled KeePassXC binary inside the `./build/src/` directory.
|
||||
|
||||
## MacOS Build Notes
|
||||
|
||||
If you installed Qt5 via Homebrew, you should be able to compile KeePassXC without any changes. If CMake fails to find your Qt installation, you can specify it manually by adding the following parameter:
|
||||
|
||||
`-DCMAKE_PREFIX_PATH=/usr/local/opt/qt/lib/cmake`
|
||||
|
||||
(or whatever your Qt installation path is)
|
||||
|
||||
When building with ASAN support on macOS, you need to use `export ASAN_OPTIONS=detect_leaks=0` before running the tests (LSAN is no supported on macOS).
|
||||
|
||||
## Windows Build Notes
|
||||
|
||||
For detailed build steps see the [Windows Build Instructions](https://github.com/keepassxreboot/keepassxc/wiki/Building-KeePassXC#windows).
|
||||
|
||||
If you are using MSVC, you may have to specify your Vcpkg toolchain by adding the following CMake parameter: `-DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake`
|
||||
|
||||
If you are using MSYS2, you have to add ```-G "MSYS Makefiles"``` at the beginning of the cmake command.
|
||||
|
||||
CMake Configuration Options
|
||||
==========================
|
||||
|
||||
## Common Parameters
|
||||
|
||||
```
|
||||
mkdir build
|
||||
cd build
|
||||
cmake -DWITH_XC_ALL=ON ..
|
||||
make
|
||||
-DCMAKE_INSTALL_PREFIX=/usr/local
|
||||
-DCMAKE_VERBOSE_MAKEFILE=ON
|
||||
-DCMAKE_BUILD_TYPE=<RelWithDebInfo/Debug/Release>
|
||||
-DWITH_GUI_TESTS=ON
|
||||
```
|
||||
|
||||
NOTE: If you are using MSYS2, you may have to add ```-G "MSYS Makefiles"``` to the beginning of the cmake command.
|
||||
## KeePassXC Parameters
|
||||
|
||||
These steps place the compiled KeePassXC binary inside the `./build/src/` directory.
|
||||
(Note the cmake notes/options below.)
|
||||
KeePassXC comes with a variety of build options that can turn on/off features. Most notably, we allow you to build the application with all TCP/IP networking code disabled. Please note that we still require and link against Qt5's network library in order to use local named pipes on all operating systems. Each of these build options are supplied at the time of calling cmake:
|
||||
|
||||
**Cmake Notes:**
|
||||
```
|
||||
-DWITH_XC_AUTOTYPE=[ON|OFF] Enable/Disable Auto-Type (default: ON)
|
||||
-DWITH_XC_YUBIKEY=[ON|OFF] Enable/Disable YubiKey HMAC-SHA1 authentication support (default: OFF)
|
||||
-DWITH_XC_BROWSER=[ON|OFF] Enable/Disable KeePassXC-Browser extension support (default: OFF)
|
||||
-DWITH_XC_NETWORKING=[ON|OFF] Enable/Disable Networking support (e.g., favicon downloading) (default: OFF)
|
||||
-DWITH_XC_SSHAGENT=[ON|OFF] Enable/Disable SSHAgent support (default: OFF)
|
||||
-DWITH_XC_FDOSECRETS=[ON|OFF] (Linux Only) Enable/Disable Freedesktop.org Secrets Service support (default:OFF)
|
||||
-DWITH_XC_KEESHARE=[ON|OFF] Enable/Disable KeeShare group synchronization extension (default: OFF)
|
||||
-DWITH_XC_ALL=[ON|OFF] Enable/Disable compiling all plugins above (default: OFF)
|
||||
|
||||
* Common cmake parameters
|
||||
-DWITH_XC_UPDATECHECK=[ON|OFF] Enable/Disable automatic updating checking (requires WITH_XC_NETWORKING) (default: ON)
|
||||
|
||||
```
|
||||
-DCMAKE_INSTALL_PREFIX=/usr/local
|
||||
-DCMAKE_VERBOSE_MAKEFILE=ON
|
||||
-DCMAKE_BUILD_TYPE=<RelWithDebInfo/Debug/Release>
|
||||
-DWITH_GUI_TESTS=ON
|
||||
```
|
||||
-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)
|
||||
-DWITH_APP_BUNDLE=[ON|OFF] Enable Application Bundle for macOS (default: ON)
|
||||
|
||||
* cmake accepts the following options:
|
||||
|
||||
```
|
||||
-DWITH_XC_AUTOTYPE=[ON|OFF] Enable/Disable Auto-Type (default: ON)
|
||||
-DWITH_XC_YUBIKEY=[ON|OFF] Enable/Disable YubiKey HMAC-SHA1 authentication support (default: OFF)
|
||||
-DWITH_XC_BROWSER=[ON|OFF] Enable/Disable KeePassXC-Browser extension support (default: OFF)
|
||||
-DWITH_XC_NETWORKING=[ON|OFF] Enable/Disable Networking support (e.g., favicon downloading) (default: OFF)
|
||||
-DWITH_XC_SSHAGENT=[ON|OFF] Enable/Disable SSHAgent support (default: OFF)
|
||||
-DWITH_XC_FDOSECRETS=[ON|OFF] (Linux Only) Enable/Disable Freedesktop.org Secrets Service support (default:OFF)
|
||||
-DWITH_XC_KEESHARE=[ON|OFF] Enable/Disable KeeShare group synchronization extension (default: OFF)
|
||||
-DWITH_XC_ALL=[ON|OFF] Enable/Disable compiling all plugins above (default: OFF)
|
||||
|
||||
-DWITH_XC_UPDATECHECK=[ON|OFF] Enable/Disable automatic updating checking (requires WITH_XC_NETWORKING) (default: ON)
|
||||
|
||||
-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)
|
||||
-DWITH_APP_BUNDLE=[ON|OFF] Enable Application Bundle for macOS (default: ON)
|
||||
|
||||
-DKEEPASSXC_BUILD_TYPE=[Snapshot|PreRelease|Release] Set the build type to show/hide stability warnings (default: "Snapshot")
|
||||
-DKEEPASSXC_DIST_TYPE=[Snap|AppImage|Other] Specify the distribution method (default: "Other")
|
||||
-DOVERRIDE_VERSION=[X.X.X] Specify a version number when building. Used with snapshot builds (default: "")
|
||||
-DGIT_HEAD_OVERRIDE=[XXXXXXX] Specify the 7 digit git commit ref for this build. Used with distribution builds (default: "")
|
||||
```
|
||||
|
||||
* 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/`
|
||||
|
||||
: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).
|
||||
-DKEEPASSXC_BUILD_TYPE=[Snapshot|PreRelease|Release] Set the build type to show/hide stability warnings (default: "Snapshot")
|
||||
-DKEEPASSXC_DIST_TYPE=[Snap|AppImage|Other] Specify the distribution method (default: "Other")
|
||||
-DOVERRIDE_VERSION=[X.X.X] Specify a version number when building. Used with snapshot builds (default: "")
|
||||
-DGIT_HEAD_OVERRIDE=[XXXXXXX] Specify the 7 digit git commit ref for this build. Used with distribution builds (default: "")
|
||||
```
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
After you have successfully built KeePassXC, install the binary by executing the following:
|
||||
|
||||
```bash
|
||||
```
|
||||
sudo make install
|
||||
```
|
||||
|
||||
You can specify the destination dir with
|
||||
```
|
||||
DESTDIR=X
|
||||
```
|
||||
|
||||
|
||||
Packaging
|
||||
=========
|
||||
|
||||
You can create a package to redistribute KeePassXC (zip, deb, rpm, dmg, etc..). Refer to [keepassxc-packaging](https://github.com/keepassxreboot/keepassxc-packaging)
|
||||
You can create a package to redistribute KeePassXC (zip, deb, rpm, dmg, etc..). Refer to [keepassxc-packaging](https://github.com/keepassxreboot/keepassxc-packaging) for packaging scripts.
|
||||
|
||||
To package using CMake, run the following command using whichever [generators](https://cmake.org/cmake/help/latest/manual/cpack-generators.7.html) you would like to package with.
|
||||
|
||||
```
|
||||
cpack -G "ZIP;WIX"
|
||||
```
|
||||
|
||||
Testing
|
||||
=======
|
||||
|
|
@ -151,7 +161,7 @@ You can perform tests on the built executables with:
|
|||
make test ARGS+="--output-on-failure"
|
||||
```
|
||||
|
||||
If you are not currently running on an X Server or Wayland, run the tests as follows:
|
||||
On Linux, if you are not currently running on an X Server or Wayland, run the tests as follows:
|
||||
```
|
||||
make test ARGS+="-E test\(cli\|gui\) --output-on-failure"
|
||||
xvfb-run -e errors -a --server-args="-screen 0 1024x768x24" make test ARGS+="-R test\(cli\|gui\) --output-on-failure"
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue