forked from organicmaps/organicmaps
[docs] Expand and simplify dev env setup docs
- add repo clone options - add Android Studio setup details - add System Requirements section - build via Android Studio by default - update build variants - add build options like -Parm64 and -Ppch - add advices for low-spec machines - move details and special options into separate subsections - update HOW_TO_USE_GRADLE.txt - update build_omim.sh usage help Signed-off-by: Konstantin Pastbin <konstantin.pastbin@gmail.com>
This commit is contained in:
Viktor Govako
parent
5da96de40a
commit
38dc07223e
4 changed files with 183 additions and 142 deletions
|
|
@ -1,19 +1,11 @@
|
|||
@NOTE1: Run <organicmaps>/tools/android/update_assets.sh once every time when assets are added/removed
|
||||
@NOTE2: To increase apk version, please edit gradle.properties
|
||||
@NOTE3: Run <organicmaps>/tools/android/set_up_android.py to set up everything.
|
||||
To build, install and run e.g. a Web Debug version on your device/emulator: './gradlew runWebDebug'
|
||||
|
||||
To clean everything, use './gradlew clean'
|
||||
Or to compile a redistributable Fdroid Beta apk for testing: './gradlew assembleFdroidBeta'
|
||||
|
||||
To build all production apks, use './gradlew assembleRelease' or './gradlew aR'
|
||||
|
||||
To build production version, use './gradlew assembleGoogleRelease'
|
||||
|
||||
To build beta, use './gradlew assembleGoogleBeta'
|
||||
|
||||
To build specific store version, use './gradlew assembleAmazonDebug'
|
||||
Or to build release apks for all flavors: './gradlew assembleRelease'
|
||||
|
||||
To see all available build targets './gradlew tasks'
|
||||
|
||||
To build and install debug version on a device './gradlew installGoogleDebug'
|
||||
To remove all intermediate build files run './gradlew clean'
|
||||
|
||||
To build, install and run application './gradlew runGoogleDebug'
|
||||
See ../docs/INSTALL.md for more detailed instructions.
|
||||
|
|
|
|||
295
docs/INSTALL.md
295
docs/INSTALL.md
|
|
@ -1,68 +1,64 @@
|
|||
# Building
|
||||
|
||||
- [System requirements](#system-requirements)
|
||||
- [Getting sources](#getting-sources)
|
||||
- [Desktop](#desktop-app)
|
||||
- [Android](#android-app)
|
||||
- [iOS](#ios-app)
|
||||
|
||||
## System requirements
|
||||
|
||||
To build and run Organic Maps you'll need a machine with at least 4Gb of RAM and 20-30Gb of disk space depending on your target platform. Expect to download 5-10Gb of files.
|
||||
|
||||
## Getting sources
|
||||
|
||||
First of all get the source code. The full Organic Maps sources repository is ~8.5Gb in size, however its possible to reduce the size e.g. if full commit history is not required.
|
||||
First of all get the source code. The full Organic Maps sources repository is ~8.5Gb in size, there are various [clone options](#special-cases-options) to reduce download size to suit your needs.
|
||||
|
||||
For _Windows 10_ enable [symlinks][git-symlinks] support in git first:
|
||||
|
||||
[git-symlinks]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-coresymlinks
|
||||
For _Windows 10_ enable [symlinks](https://git-scm.com/docs/git-config#Documentation/git-config.txt-coresymlinks) support in git first:
|
||||
|
||||
```bash
|
||||
git config --global core.symlinks true
|
||||
```
|
||||
|
||||
If you plan to contribute and propose pull requests then fork the repo https://github.com/organicmaps/organicmaps first.
|
||||
Clone the repository including all submodules:
|
||||
|
||||
Clone the main repository (~5.5Gb):
|
||||
(if you plan to contribute and propose pull requests then use a web interface at https://github.com/organicmaps/organicmaps to fork the repo first and use your fork's url in the command below)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/organicmaps/organicmaps.git
|
||||
git clone --recurse-submodules https://github.com/organicmaps/organicmaps.git
|
||||
```
|
||||
or your fork of it:
|
||||
```bash
|
||||
git clone https://github.com/<your-github-name>/organicmaps.git
|
||||
```
|
||||
|
||||
Add a `--filter=blob:limit=128k` option to above command to make a _partial clone_ of just ~1.2Gb, i.e. blob files over 128k in size will be excluded form the history and downloaded on-demand - should be suitable for a generic development use.
|
||||
|
||||
And/or add a `--depth=1` option to make a _shallow copy_ (and possibly a `--no-single-branch` to have all branches not just `master`), i.e. omit history retaining current commits only - suitable for one-off builds.
|
||||
|
||||
Go into the cloned repo:
|
||||
```bash
|
||||
cd organicmaps
|
||||
```
|
||||
|
||||
Clone git submodules (~3Gb):
|
||||
Configure the repository for an opensource build:
|
||||
|
||||
```bash
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
Add a `--depth=1` option to make a _shallow copy_ of just ~1.3Gb - should be suitable for a generic development if no work on submodules planned.
|
||||
|
||||
Configure the repository:
|
||||
(if you plan to publish the app privately in stores check [special options](#special-cases-options))
|
||||
|
||||
```bash
|
||||
./configure.sh
|
||||
```
|
||||
|
||||
**Windows 10:** Use WSL to run `./configure.sh`:
|
||||
For _Windows 10_: Use WSL to run `./configure.sh`:
|
||||
|
||||
```bash
|
||||
bash ./configure.sh # execute the script by using Ubuntu WSL VM
|
||||
```
|
||||
|
||||
By default the repo is configured for an opensource build. Configure for a private build if private keys and configs are needed to publish the app in stores e.g. in Google Play (check options via `./configure.sh --help`):
|
||||
### Special cases options
|
||||
|
||||
```bash
|
||||
./configure.sh <private-repo-name>
|
||||
```
|
||||
If all you want is just a one-off build or your Internet bandwidth or disk space are limited then add following options to the `git clone` command:
|
||||
|
||||
- a `--filter=blob:limit=128k` option to make a _partial clone_ (saves ~4Gb), i.e. blob files over 128k in size will be excluded from the history and downloaded on-demand - should be suitable for a generic development use;
|
||||
|
||||
- a `--depth=1` option to make a _shallow copy_ (and possibly a `--no-single-branch` to have all branches not just `master`), i.e. omit history while retaining current commits only (saves ~4.5Gb) - suitable for one-off builds;
|
||||
|
||||
- a `--shallow-submodules` option to _shallow clone_ the submodules (save ~1.3Gb) - should be suitable for a generic development if no work on submodules is planned.
|
||||
|
||||
To be able to publish the app in stores e.g. in Google Play its necessary to populate some configs with private keys, etc.
|
||||
Check `./configure.sh --help` to see how to copy the configs automatically from a private repo.
|
||||
|
||||
## Desktop app
|
||||
|
||||
|
|
@ -76,9 +72,9 @@ You need a Linux or a Mac machine to build a desktop version of Organic Maps.
|
|||
|
||||
Ensure that you have at least 20GB of free space.
|
||||
|
||||
Install Cmake, Boost, Qt 5 and other dependencies.
|
||||
Install Cmake (**3.18.1** minimum), Boost, Qt 5 and other dependencies.
|
||||
|
||||
**Ubuntu 20.04**:
|
||||
_Ubuntu 20.04:_
|
||||
|
||||
```bash
|
||||
sudo apt-get update && sudo apt-get install -y \
|
||||
|
|
@ -95,7 +91,7 @@ sudo apt-get update && sudo apt-get install -y \
|
|||
zlib1g-dev
|
||||
```
|
||||
|
||||
**Fedora 33**:
|
||||
_Fedora 33:_
|
||||
|
||||
```bash
|
||||
sudo dnf install -y \
|
||||
|
|
@ -107,7 +103,7 @@ sudo dnf install -y \
|
|||
sqlite-devel
|
||||
```
|
||||
|
||||
**macOS**:
|
||||
_macOS:_
|
||||
|
||||
```bash
|
||||
brew install cmake qt@5
|
||||
|
|
@ -115,45 +111,28 @@ brew install cmake qt@5
|
|||
|
||||
### Building
|
||||
|
||||
With all tools installed, just run `tools/unix/build_omim.sh`.
|
||||
It will build both debug and release versions to `../omim-build-<buildtype>`.
|
||||
Command-line switches are:
|
||||
|
||||
- `-r` to build a release version
|
||||
- `-d` to build a debug version
|
||||
- `-c` to delete target directories before building
|
||||
- `-s` to not build a desktop app, when you don't have desktop Qt libraries.
|
||||
- `-p` with a path to where the binaries will be built.
|
||||
|
||||
After switches, you can specify a target (everything by default). For example,
|
||||
to build a generator tool release version only:
|
||||
|
||||
```
|
||||
tools/unix/build_omim.sh -r generator_tool
|
||||
To build a debug version of the desktop app:
|
||||
```bash
|
||||
tools/unix/build_omim.sh -d desktop
|
||||
```
|
||||
|
||||
Targets list can be viewed:
|
||||
The output binary will go into `../omim-build-debug`.
|
||||
|
||||
Check `tools/unix/build_omim.sh -h` for more build options, e.g. to build a release.
|
||||
|
||||
Besides _desktop_ there are other targets like _generator_tool_, to see a full list execute:
|
||||
|
||||
```bash
|
||||
cmake --build ../omim-build-<buildtype> --target help
|
||||
tools/unix/build_omim.sh -d help
|
||||
```
|
||||
|
||||
If you have Qt installed in an unusual directory, use `QT_PATH` variable (`SET (QT_PATH "your-path-to-qt")`). You can skip building tests
|
||||
with `CMAKE_CONFIG=-DSKIP_TESTS` variable. You would need 1.5 GB of memory
|
||||
to compile the `stats` module.
|
||||
|
||||
The `build_omim.sh` script basically runs these commands:
|
||||
|
||||
cmake <path_to_omim> -DCMAKE_BUILD_TYPE={Debug|Release}
|
||||
make [<target>] -j <number_of_processes>
|
||||
|
||||
### Running
|
||||
|
||||
The generated binaries appear in `../omim-build-<buildtype>`.
|
||||
|
||||
Run `OMaps` binary from `../omim-build-<buildtype>`, for example, for release:
|
||||
|
||||
**Linux**:
|
||||
_Linux:_
|
||||
|
||||
```bash
|
||||
../omim-build-release/OMaps -data_path ./data
|
||||
|
|
@ -167,7 +146,7 @@ ln -s ../organicmaps/data ./data
|
|||
./OMaps -data_path ./data
|
||||
```
|
||||
|
||||
**macOS**:
|
||||
_macOS:_
|
||||
|
||||
```bash
|
||||
../omim-build-release/OMaps.app/Contents/MacOS/OMaps
|
||||
|
|
@ -214,6 +193,18 @@ ln -s ../data/ data
|
|||
|
||||
Some tests [are known to be broken](https://github.com/organicmaps/organicmaps/issues?q=is%3Aissue+is%3Aopen+label%3ATests).
|
||||
|
||||
### More options
|
||||
|
||||
If you have Qt installed in an unusual directory, use `QT_PATH` variable (`SET (QT_PATH "your-path-to-qt")`). You can skip building tests
|
||||
with `CMAKE_CONFIG=-DSKIP_TESTS` variable. You would need 1.5 GB of memory
|
||||
to compile the `stats` module.
|
||||
|
||||
The `build_omim.sh` script basically runs these commands:
|
||||
```bash
|
||||
cmake <path_to_omim> -DCMAKE_BUILD_TYPE={Debug|Release}
|
||||
<make or ninja> [<target>] -j <number_of_processes>
|
||||
```
|
||||
|
||||
## Android app
|
||||
|
||||
### Preparing
|
||||
|
|
@ -224,8 +215,7 @@ Ensure that you have at least 30GB of free space.
|
|||
|
||||
Install [Android Studio](https://developer.android.com/studio).
|
||||
|
||||
Install [Android SDK](https://developer.android.com/sdk/index.html) and
|
||||
[NDK](https://developer.android.com/tools/sdk/ndk/index.html):
|
||||
Install Android SDK and NDK:
|
||||
|
||||
- Run the Android Studio.
|
||||
- Open "SDK Manager" (under "More Actions" in a welcome screen or a three-dot menu in a list of recent projects screen or "Tools" top menu item in an open project).
|
||||
|
|
@ -236,22 +226,70 @@ Install [Android SDK](https://developer.android.com/sdk/index.html) and
|
|||
- Select "CMake" version **3.18.1**.
|
||||
- Click "OK" and wait for downloads and installation to finish.
|
||||
|
||||
Alternatively, you can install only
|
||||
[Android SDK](https://developer.android.com/sdk/index.html) and
|
||||
[NDK](https://developer.android.com/tools/sdk/ndk/index.html) without
|
||||
installing Android Studio. Please make sure that SDK for API Level 30,
|
||||
NDK version **21.X.Y** and CMake version **3.18.XX** are installed.
|
||||
Configure the repo with Android SDK and NDK paths:
|
||||
|
||||
Configure `PATH` to prefer `cmake` from Android SDK/NDK instead of
|
||||
installed in the system:
|
||||
_Linux:_
|
||||
```bash
|
||||
./tools/android/set_up_android.py --sdk $HOME/Android/Sdk
|
||||
```
|
||||
|
||||
**Linux**:
|
||||
_macOS:_
|
||||
```bash
|
||||
./tools/android/set_up_android.py --sdk $HOME/Library/Android/Sdk
|
||||
```
|
||||
|
||||
_Windows 10:_ no action needed, should work out of the box.
|
||||
|
||||
In Android Studio open the project in `android/` directory.
|
||||
Make sure the Studio has at least 1920Mb max heap size in "File > Settings... > Appearance & Behavior > System Settings > Memory Settings", otherwise it might get stuck on "Updating indexes".
|
||||
|
||||
Setup a virtual device to use [emulator]((https://developer.android.com/studio/run/emulator)) ("Tools > AVD Manager") or [use a hardware device for debugging](https://developer.android.com/studio/run/device).
|
||||
|
||||
### Building
|
||||
|
||||
There is a matrix of different build variants:
|
||||
|
||||
- _Type_:
|
||||
- `Debug` is a debug version with all checks enabled.
|
||||
- `Beta` is a manual pre-release build for testing.
|
||||
- `Release` is a fully optimized version for app stores.
|
||||
|
||||
- _Flavor_:
|
||||
- `Web` is a light apk without any bundled maps.
|
||||
- `Google` is a full Google Play store version including a low-zoom overview world map.
|
||||
- `Fdroid` is a version for publishing on [F-Droid](https://f-droid.org/) open source apps store (no bundled maps and no Google services).
|
||||
- ...and other flavors like `Huawei`.
|
||||
|
||||
You can choose a build variant in Android Studio's "Build > Select Build Variant..." menu. There you can also choose a target architecture (Active ABI) like _x86_64_ (for e.g. emulator) or _arm64-v8a_ (many modern devices).
|
||||
|
||||
To build and run the app in the emulator or on a hardware device use a "Run > Run (android)" menu item.
|
||||
|
||||
To build a redistributable apk use a "Build > Build Bundle(s) / APK(s) > Build APK(s)" menu item. Generated apks are stored in `build/outputs/apk/`.
|
||||
|
||||
See also https://developer.android.com/studio/run.
|
||||
|
||||
|
||||
### Debugging
|
||||
|
||||
To enable logging in case of crashes, after installing a debug version, run:
|
||||
|
||||
```bash
|
||||
adb shell pm grant app.organicmaps.debug android.permission.READ_LOGS
|
||||
```
|
||||
|
||||
### More options
|
||||
|
||||
#### Building from the command line
|
||||
|
||||
First configure `PATH` to prefer `cmake` from Android SDK/NDK instead of one installed in the system:
|
||||
|
||||
_Linux:_
|
||||
|
||||
```bash
|
||||
export PATH=$HOME/Android/Sdk/cmake/3.18.1/bin:$PATH
|
||||
```
|
||||
|
||||
**macOS**:
|
||||
_macOS:_
|
||||
|
||||
```bash
|
||||
export PATH=$HOME/Library/Android/Sdk/cmake/3.18.1/bin:$PATH
|
||||
|
|
@ -263,74 +301,83 @@ Check if you have a system-wide Java runtime environment (JRE) installed:
|
|||
java -version
|
||||
```
|
||||
|
||||
If your system doesn't have a JRE installed or Java version is less than 11 (openjdk) or you want command line builds to use a JRE version bundled with the Studio then set `JAVA_HOME` environment variable:
|
||||
If your system doesn't have a JRE installed or Java version is less than 11 (openjdk)
|
||||
or you want command line builds to use a JRE version bundled with the Studio
|
||||
then set `JAVA_HOME` environment variable:
|
||||
|
||||
**Linux**:
|
||||
_Linux:_
|
||||
|
||||
```bash
|
||||
export JAVA_HOME=*A-PATH-TO-YOUR-ANDROID-STUDIO-INSTALLATION*/android-studio/jre
|
||||
export JAVA_HOME=<path-to-android-studio-installation>/android-studio/jre
|
||||
```
|
||||
|
||||
**macOS**:
|
||||
_macOS:_
|
||||
|
||||
```bash
|
||||
export JAVA_HOME=*A-PATH-TO-YOUR-ANDROID-STUDIO-INSTALLATION*/Contents/jre/Contents/Home
|
||||
export JAVA_HOME=<path-to-android-studio-installation>/Contents/jre/Contents/Home
|
||||
```
|
||||
|
||||
**Windows 10.** Alternative way is to initialize Boost manually:
|
||||
Run the builds from the android subdirectory of the repo:
|
||||
```bash
|
||||
cd android
|
||||
```
|
||||
|
||||
To build, install and run e.g. a _Web Debug_ version on your device/emulator:
|
||||
|
||||
```bash
|
||||
./gradlew runWebDebug
|
||||
```
|
||||
|
||||
Or to compile a redistributable _Fdroid Beta_ apk for testing:
|
||||
|
||||
```bash
|
||||
./gradlew assembleFdroidBeta
|
||||
```
|
||||
|
||||
Or to build _Release_ apks for all _Flavors_:
|
||||
|
||||
```bash
|
||||
./gradlew assembleRelease
|
||||
```
|
||||
|
||||
Run `./gradlew tasks` to see all possible build variants.
|
||||
|
||||
Intermediate files for each build (_Type_ + _Flavor_ + target arch) take ~3-4.5Gb of space.
|
||||
To remove all intermediate build files run `./gradlew clean`.
|
||||
|
||||
By default the build will run for all 3 target architectures: _arm64-v8a_, _armeabi-v7a_ and _x86_64_. To speed up your build include only the arch you need by adding e.g. a `-Parm64` option to the gradle build command (other options are `-Parm32` for _armeabi-v7a_, `-Px64` for _x86_64_ and `-Px86` for _x86_).
|
||||
|
||||
To create separate apks for all target arches add a `-PsplitApk` option (by default all arches are combined in one "fat" apk).
|
||||
|
||||
Adding a `-Ppch` (use precompiled headers) option makes builds ~15% faster.
|
||||
|
||||
If a running build makes your computer slow and laggish then try lowering the priority of the build process by adding a `--priority=low` option.
|
||||
|
||||
See also https://developer.android.com/studio/build/building-cmdline.
|
||||
|
||||
#### Reduce resource usage
|
||||
|
||||
You can install
|
||||
[Android SDK](https://developer.android.com/sdk/index.html) and
|
||||
[NDK](https://developer.android.com/tools/sdk/ndk/index.html) without
|
||||
Android Studio. Please make sure that SDK for API Level 30,
|
||||
NDK version **21.4.7075529** and CMake version **3.18.1** are installed.
|
||||
|
||||
If you are low on RAM, disk space or traffic there are ways to reduce system requirements:
|
||||
- in Android Studio enable "File > Power Save Mode";
|
||||
- don't install Android Studio, run builds and emulator from command line;
|
||||
- build only for target arches you actually need, e.g. `arm64`;
|
||||
- for debugging use an older emulated device with low RAM and screen resolution, e.g. "Nexus S";
|
||||
- make sure the emulator uses [hardware acceleration](https://developer.android.com/studio/run/emulator-acceleration);
|
||||
- don't use emulator, debug on a hardware device instead.
|
||||
|
||||
#### Windows 10: Manual Boost library initialization
|
||||
|
||||
1. Install Visual Studio 2019 Community Edition.
|
||||
2. Add cl.exe to your PATH (`C:\\Program Files (x86)\\Microsoft Visual Studio\\2019\\Community\\VC\\Auxiliary\\Build\\vcvars32.bat`).
|
||||
3. Run `./configure.sh` from _Git (for Window) Bash_ and ignore all errors related to Boost.
|
||||
4. Go to `./3party/boost`, run `./bootstrap.bat`, and then `b2 headers` to configure Boost.
|
||||
|
||||
Set Android SDK and NDK path:
|
||||
|
||||
```bash
|
||||
# Linux
|
||||
./tools/android/set_up_android.py --sdk $HOME/Android/Sdk
|
||||
# MacOS
|
||||
./tools/android/set_up_android.py --sdk $HOME/Library/Android/Sdk
|
||||
# Windows 10
|
||||
# no actions needed, should work out of the box
|
||||
```
|
||||
|
||||
### Building
|
||||
|
||||
There is a matrix of different build variants:
|
||||
|
||||
- Type:
|
||||
|
||||
- `Debug` is a debug version with all checks enabled.
|
||||
- `Beta` is a manual pre-release build.
|
||||
- `Release` is a fully optimized version for stores.
|
||||
|
||||
- Flavor:
|
||||
- `Web` is a light apk without any bundled maps.
|
||||
- `Google` is a full store version without low-zoom overview world map.
|
||||
- There are also `Amazon`, `Samsung`, `Xiaomi`, `Yandex`
|
||||
and other targets.
|
||||
|
||||
To run a debug version on your device/emulator:
|
||||
|
||||
```bash
|
||||
(cd android; ./gradlew clean runWebDebug)
|
||||
```
|
||||
|
||||
To compile a redistributable `.apk` for testing:
|
||||
|
||||
```bash
|
||||
(cd android; ./gradlew clean assembleWebBeta)
|
||||
ls -la ./android/build/outputs/apk/android-web-beta-*.apk
|
||||
```
|
||||
|
||||
### Debugging
|
||||
|
||||
To enable logging in case of crashes, after installing a debug version, run:
|
||||
|
||||
```bash
|
||||
adb shell pm grant app.organicmaps.debug android.permission.READ_LOGS
|
||||
```
|
||||
|
||||
## iOS app
|
||||
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ git checkout release-92
|
|||
|
||||
The app version can be found in the "About" section in the settings menu of OMaps.
|
||||
|
||||
1. [Build and install generator_tool.](https://github.com/organicmaps/organicmaps/blob/master/docs/INSTALL.md#maps-generator)
|
||||
1. [Build and install generator_tool.](https://github.com/organicmaps/organicmaps/blob/master/docs/INSTALL.md#desktop-app)
|
||||
2. Change directory:
|
||||
|
||||
```sh
|
||||
|
|
|
|||
|
|
@ -30,11 +30,14 @@ while getopts ":cdrstagjlp:" opt; do
|
|||
;;
|
||||
t) OPT_DESIGNER=1 ;;
|
||||
*)
|
||||
echo "This tool builds omim"
|
||||
echo "This tool builds Organic Maps"
|
||||
echo "Usage: $0 [-d] [-r] [-c] [-s] [-t] [-a] [-g] [-j] [-l] [-p PATH] [target1 target2 ...]"
|
||||
echo
|
||||
echo -e "-d\tBuild omim-debug"
|
||||
echo -e "-r\tBuild omim-release"
|
||||
echo "By default both debug and release versions are built"
|
||||
echo "and binaries are put into ../omim-build-<buildtype> dir."
|
||||
echo
|
||||
echo -e "-d\tBuild debug version"
|
||||
echo -e "-r\tBuild release version"
|
||||
echo -e "-c\tClean before building"
|
||||
echo -e "-s\tSkip desktop app building"
|
||||
echo -e "-t\tBuild designer tool (only for MacOS X platform)"
|
||||
|
|
@ -43,7 +46,6 @@ while getopts ":cdrstagjlp:" opt; do
|
|||
echo -e "-p\tDirectory for built binaries"
|
||||
echo -e "-j\tGenerate compile_commands.json"
|
||||
echo -e "-l\tLaunches built binary(ies), useful for tests"
|
||||
echo "By default both configurations is built."
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue