diff --git a/android/HOW_TO_USE_GRADLE.txt b/android/HOW_TO_USE_GRADLE.txt index 24689f0dc7..584cba4255 100644 --- a/android/HOW_TO_USE_GRADLE.txt +++ b/android/HOW_TO_USE_GRADLE.txt @@ -1,19 +1,11 @@ -@NOTE1: Run /tools/android/update_assets.sh once every time when assets are added/removed -@NOTE2: To increase apk version, please edit gradle.properties -@NOTE3: Run /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. diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 52d0b83f67..db3f6c97b3 100644 --- a/docs/INSTALL.md +++ b/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//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 -``` +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-`. -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- --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 -DCMAKE_BUILD_TYPE={Debug|Release} - make [] -j - ### Running The generated binaries appear in `../omim-build-`. Run `OMaps` binary from `../omim-build-`, 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 -DCMAKE_BUILD_TYPE={Debug|Release} + [] -j +``` + ## 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=/android-studio/jre ``` -**macOS**: +_macOS:_ ```bash -export JAVA_HOME=*A-PATH-TO-YOUR-ANDROID-STUDIO-INSTALLATION*/Contents/jre/Contents/Home +export JAVA_HOME=/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 diff --git a/tools/python/maps_generator/README.md b/tools/python/maps_generator/README.md index 806e7f8e83..ee98370fc8 100644 --- a/tools/python/maps_generator/README.md +++ b/tools/python/maps_generator/README.md @@ -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 diff --git a/tools/unix/build_omim.sh b/tools/unix/build_omim.sh index 5f277213ff..1b7e1f9a94 100755 --- a/tools/unix/build_omim.sh +++ b/tools/unix/build_omim.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- 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