qwe/keepass2android
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

relocate build.readme.md and mention it in README.md

Browse Source
This commit is contained in:
tenzap
2022-12-09 13:57:37 +01:00
parent 2c128794ac
commit 63f6c1e5cf
3 changed files with 5 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

247
src/build.readme.md
View File

@@ -1,247 +0,0 @@
# How to build Keepass2Android
## Overview
Keepass2Android is a Mono for Android app. This means that you need Xamarin's Mono for Android to build it. However, it also uses several components written in Java, so there are also Android-Studio projects involved. To make things even worse, parts of the keyboard and kdb-library are written in native code.
To build KP2A from scratch, you need:
- Xamarin's Mono for Android (also included in Visual Studio)
- Android SDK & NDK
Prior to building Keepass2Android, you need to build some of its components (from command line). Then you can build the full project either through Visual Studio, or through command line.
By using the command line, you can build on Windows, macOS or Linux.
## Prerequisites
### Common to all architectures
- Install Android SDK & NDK (either manually with Google's [sdkmanager](https://developer.android.com/studio/command-line/sdkmanager), or through Android Studio). Visual Studio also installs a version of it, but in the end the directory must be writable and in a path without spaces (see below) so as to be able to build the components.
- Fetch the main repository of Keepass2Android and all submodules
- Note that VisualStudio can do this for you, otherwise run:
- `git submodule init && git submodule update`
### On Windows or macOS
- Install Visual Studio (for example 2019) with Xamarin.Android (ie. with capability to build Android apps). This should provide the needed tools like
- Xamarin.Android
- MSBuild
- If you plan to build also from the command line:
- Install the MSVC build tools of visual studio. They provide the `vcvarsall.bat` file which among other things adds MSBuild to the PATH.
- Install [NuGet](https://www.nuget.org/downloads) to build also with "make". Alternatively, on Windows, if you use [chocolatey](https://chocolatey.org), run as administrator:
- `choco install nuget.commandline`
- Check that you have access to 'GNU make'.
- On Windows, it is usually not available by default. But the Android NDK provides it. You can find it in `%ANDROID_NDK_ROOT%\prebuilt\windows-x86_64\bin\make.exe`. Alternatively, on Windows, if you use [chocolatey](https://chocolatey.org), run as administrator:
- `choco install make`
- On macOS, it is usually only installed if you have developer command line tools installed or if you use [homebrew](https://brew.sh) or [macports](https://www.macports.org/). As an alternative it may be available in the Android NDK at `%ANDROID_NDK_ROOT%/prebuilt/darwin-x86_64/bin/make`.
### On Linux
- Install [Mono](https://www.mono-project.com/)
- This should provide `msbuild` & `xabuild` binary
- On Debian, after having added the repo from above, install with `apt install -t <repo_name> mono-complete`. A value for `<repo_name>` could be `stable-buster` for example, depending on which one you chose.
- Install Xamarin.Android
- Option 1: Use the mono-project [CI builds](https://dev.azure.com/xamarin/public/_build/latest?definitionId=48&branchName=main&stageName=Linux)
- Option 2: [Build it from source](https://github.com/xamarin/xamarin-android/blob/master/Documentation/README.md#building-from-source)
- Install NuGet package of your distribution
- On Debian/Ubuntu: `apt install nuget`
- Install [libzip](https://libzip.org/) for your distribution.
- Note: Xamarin seems to require `libzip4`.
- On Debian/Ubuntu, install it with `apt install libzip4`.
- Other distributions ship only `libzip5`. As a dirty workaround, it's possible to symlink `libzip.so.5` to `libzip.so.4`. Luckily, it appears to be working. For example:
- `sudo ln -s /usr/lib/libzip.so.5 /usr/lib/libzip.so.4`
- or `sudo ln -s /usr/lib64/libzip.so.5 /usr/lib/libzip.so.4`
## Building the required components:
This is done on the command line and requires the Android SDK & NDK.
### On Windows
- Setup your environment:
- Set these environment variables for Android's SDK & NDK
- `ANDROID_HOME` (for example `set ANDROID_HOME=C:\PATH\TO\android-sdk\`)
- `ANDROID_SDK_ROOT` (for example `set ANDROID_SDK_ROOT=C:\PATH\TO\android-sdk\`)
- `ANDROID_NDK_ROOT` (for example `set ANDROID_NDK_ROOT=C:\PATH\TO\android-sdk\ndk\version\`)
**Note**: If the path to the Android SDK contains spaces, you **must** do one of these:
- either put the Android SDK into a path without spaces.
- or create a symlink to that path which doesn't contain spaces. Attention: this requires **administrator** priveleges. For example:
```
IF NOT EXIST C:\Android ( MKDIR C:\Android ) &&
MKLINK /D C:\Android\android-sdk "C:\Program Files (x86)\Android\android-sdk"
```
This is because [Android NDK doesn't support being installed in a path with spaces](https://github.com/android/ndk/issues/1400).
**Note**: The Android SDK path will require to be writeable because during the build, some missing components might be downloaded & installed.
- If you have "GNU make" available on your windows system, you may build by using the Makefile. You can also find a `make` executable in `%ANDROID_NDK_ROOT%\prebuilt\windows-x86_64\bin\make.exe`. To use it, see the instructions for Linux/macOS. Basically, just run `make` or `mingw32-make` depending on which distribution of GNU make for windows you have installed.
- Otherwise proceed as below:
1. Build argon2
```
cd src/java/argon2
%ANDROID_NDK_ROOT%/ndk-build.cmd
```
1. Build the other java components
```
cd src/build-scripts
build-java.bat
```
`build-java.bat` will call `gradlew` for several Java modules.
**Notes:**
- For building the java parts, it is suggested to keep a short name (e.g. "c:\projects\keepass2android") for the root project directory. Otherwise the Windows path length limit might be hit when building.
- Before building the java parts, make sure you have set the ANDROID_HOME variable or create a local.properties file inside the directories with a gradlew file. It is recommended to use the same SDK location as that of the Xamarin build.
### On Linux/macOS
- Setup your environment:
- Set these environment variables for Android's SDK & NDK
- `ANDROID_HOME` (for example `export ANDROID_HOME=/path/to/android-sdk/`)
- `ANDROID_SDK_ROOT` (for example `export ANDROID_SDK_ROOT=/path/to/android-sdk/`)
- `ANDROID_NDK_ROOT` (for example `export ANDROID_NDK_ROOT=/path/to/android-sdk/ndk/version`)
- Update your PATH environment variable so that it can access `nuget`, `msbuild` or `xabuild` (for linux):
- On Linux:
- add `xabuild` to your path: `export PATH=/path/to/xamarin.android-oss/bin/Release/bin/:$PATH`
- On macOS:
- you may similarly need to add `msbuild` & `nuget` to your PATH.
- Start the build:
- This will use the Makefile at the root of the project (requires GNU make). To build everything (components & Keepass2Android APK) in a single command simply run:
```
make
```
- Otherwise, if you prefer to do step by step
1. Build argon2
```
make native
```
1. Build the other java components
```
make java
```
## Building Keepass2Android:
These are the basic steps to build Keepass2Android. You can also build Keepass2Android Offline. For this, configure the build by using the [Flavors](#Flavors).
### With Visual Studio
- On windows or on macOS open the src/KeePass.sln file with visual studio, and choose to build the project named 'keepass2android-app'
### Command Line
#### Windows
```
cd src/build-scripts
build-xamarin.bat
```
`build-xamarin.bat` will first make sure that you have all files at their place. (There is a "secret" file for Dropbox SDK keys which is not in the repo, this is replaced with a dummy file).
Use `build-xamarin_nonet.bat` to build the 'nonet' flavor.
#### Macos & Linux
to build the APK, simply run:
```
make
```
or to skip building the APK:
```
make msbuild
```
## Where is the APK ?
The Apk can be installed on a device.
It is located in `src/keepass2android/bin/*/*-Signed.apk`
If you build with Visual Studio, the APK is not produced automatically. You need to perform some extra step. See the documentation of Visual Studio on how to proceed.
## Flavors
Keepass2Android is distributed in two flavors.
- Keepass2Android (aka `net`)
- Keepass2Android Offline (aka `nonet`)
The flavor is set through a MSBuild Property named "`Flavor`". The possible values are '`Net`' and '`NoNet`'.
The value of the Flavor property is used in 2 projects:
- `keepass2android-app` (in `src/keepass2android`)
- `Kp2aBusinessLogic` (in `src/keepass2android`)
Its value is set inside the `*.csproj` file (XML format) of each project in the `Project`/`PropertyGroup`/`Flavor` node.
By default its value is set to an empty string so that development is made with `AndroidManifest_debug.xml` on the '`net`' flavor.
This is the behaviour of the build system depending on the value of Flavor:
| Flavor | What is built | `AndroidManifest.xml` used |
| ----- | ----- | ----- |
| `` (empty string): This is the default value. | Keepass2Android | `AndroidManifest_debug.xml` |
| `Net` | Keepass2Android | `AndroidManifest_net.xml` |
| `NoNet` | Keepass2Android Offline | `AndroidManifest_nonet.xml` |
### Select/Change flavor:
When building, by default, the flavor is not set. So the value used is the value of the Flavor property in *.csproj file. This should result on doing a build of the 'net' flavor.
You can force the Flavor by setting the Flavor property.
Proceed this way:
#### Command line
##### Windows
On Windows, you can use the `src/build-scripts/build-xamarin_nonet.bat` script to build 'NoNet'.
```
cd src/build-scripts
build-xamarin_nonet.bat
```
##### Macos & Linux
To force building 'net' with `make`, run:
```
make Flavor=Net
```
To build 'nonet' with `make`, run:
```
make Flavor=NoNet
```
##### MSBuild
To build with MSBuild directly on the command line, set the flavor with `-p:Flavor=value` argument. For example:
```
MSBuild src/KeePass.sln ... -p:Flavor=NoNet
```
#### Visual Studio
When building with Visual Studio, edit the `*.csproj` file (XML format) and set the value in the `Project`/`PropertyGroup`/`Flavor` node. This is needed only for the projects that use the flavors.
**Note:** When switching between flavors, be sure to clean the previous build before.
## Makefile
It is possible to override the project's default 'Flavor' (Net, NoNet) and 'Configuration' (Release, Debug) by passing it as argument to `make`. See the header of the Makefile to see what can be done.