Improve building / dev env setup instructions

[pastk]

I'm willing to improve development environment setup / building documentation (Android-specific mostly), i.e. docs/INSTALL.md.
I have a few ideas and willing to propose PRs, however I need to clarify some points and get feedback first.

Dedup the "getting sources"

At the moment "getting sources" sub-section is present in each target (Android, Desktop, iOS) in almost identical form.
I want to move it in a separate section preceding target-specific instructions.

Android

1. What does the ./configure.sh do and what is the difference between open-source and private builds?

2. Is it worthwhile to document the splitApk build param - and why its not used by default? And the pch (pre-compiled headers) param?

3. Document other build params like -Parm64

4. Add more details about studio setup, e.g. memory setting (I couldn't get the project open - it was stuck/frozen at "updating indexes" - until I increased studio's heap size from default 1.9Gb to 2.5Gb ), setting up virtual device or using physical one...

5. Could we lower org.gradle.jvmargs=-Xmx8g in gradle.properties to some minimally required setting? Newbies might have impression that 8Gb is the minimum to be able to build, however I found it builds fine using 3Gb (didn't try less yet). Those devs who have more RAM can increase this setting locally.

6. Does org.gradle.parallel=true actually needed and makes a difference? As far as I understand it makes a difference to multi-projects builds only (and OM is a single project build or am I mistaken here?) - at least that setting didn't do any difference for me.

7. Why suggest to always run clean before building (e.g. in gradlew clean assembleXXX)? My understanding is that it'll make a build slower by forcing to re-compile everything from scratch instead of re-building only the parts that were changed

8. Update build flavors, e.g. remove yandex, xiaomi, add fdroid...

9. Update HOW_TO_USE_GRADLE.txt and link to it from the INSTALL.md.

10. Maybe I'll add a separate sub-section with advice for people with low spec machines, e.g. how to conserve disk space and ram.

[biodranik]

1. ./configure.sh sets up some important stuff for desktop and mobile builds. It could be a good idea to split what is required for mobile builds and desktop builds to make it easier. You can check this script and see what is going on inside. Private builds use private keys and configs used to publish apps in Google Play. Open-source builds do not use private keys and configs.
2. Please document splitApk. Why do you think it should be used by default? Regarding pch (Precompiled Headers), we didn't check it yet. Do you see any difference in compilation speed with and without it (after cleaning caches)?
3. Yes!
4. Yes!
5. No, but please mention it in the documentation.
6. Probably it's not needed. Do you see any speed difference with and without it (after cleaning all caches, of course)?
7. clean is not needed before every build, it looks like a historic artifact.
8. We'll update/reuse flavors later. It makes sense to publish the app everywhere.
9. Yes!
10. Good idea!

[biodranik]

Cool, thanks! Let's remove parallel and document pch.

[pastk]

I also ran a few tests to see how JVM memory settings affect build times.
My conlusion is that a bigger JVM heap size doesn't affect the build speed - and it makes sense as 90+% of the build time is taken by cxx compilation which doesn't have anything to do with JVM. So the heap size should be big enough to run all the tasks, but there is no point to keep it higher.
So my suggestion is to reduce the current -Xmx8g setting to a -Xmx1024m.

Details:
Build cmd ./gradlew -Parm64 -Ppch --no-parallel --no-build-cache --rerun-tasks --profile assembleFdroidDebug

By default (if there is no explicit setting in gradle.properties) gradle daemon is started with just -Xms256m -Xmx512m:
run1: 17m 2s; run2: 16m 59s

With a org.gradle.jvmargs=-Xmx4g in gradle.properties:
run1: 17m 1s; run2: 17m 19s

However with the default -Xms256m -Xmx512m setting the build failed for FdroidRelease at Task :minifyFdroidReleaseWithR8: ERROR:R8: java.lang.OutOfMemoryError: Java heap space.

So I increased it to 1Gb (org.gradle.jvmargs=-Xmx1024m in gradle.properties) and build was successful:
run1: 22m 18s

2Gb setting:
run1: 22m 11s

4Gb setting:
run1: 21m 53s

[biodranik]

Good, 1Gb should be enough.

[pastk]

For 1. configure.sh private mode I understand that the private repo is expected to contain only secure/private config files in question and the script just copies them over to the local "main" repository. Is that right?

[biodranik]

Correct.

[pastk]

A PR to Disable parallel builds and reduce JVM heap: #1548

[pastk]

A PR to Dedup and improve Getting Sources section: #1551

[pastk]

Add details and simplify the main flow: #1568

[pastk]

android/HOW_TO_USE_GRADLE.txt contains following:

@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

Are those notes relevant still? I.e. its not clear how to increase the apk version.

Other that those lines it seems that android/HOW_TO_USE_GRADLE.txt duplicates docs/INSTALL.md.
So my suggestion is to add missing bits into docs/INSTALL.md and remove android/HOW_TO_USE_GRADLE.txt.

[biodranik]

Version is automatically generated now, so the doc reference can be removed.

Script creates symlinks, so it should be actual now. Let's leave its doc here and also duplicate it in INSTALL.md or even move to CONTRIBUTE.md (as it's relevant to development, not for building/installing)

[pastk]

Hmm, but there is no <organicmaps>/tools/android/update_assets.sh?

[biodranik]

Right! It was removed… There is ./android/script/replace_links.bat left to workaround missing symlinks for git, but that is not the case anymore with working symlinks.

[pastk]

cmake --build ../omim-build-debug --target help is not useful or friendly to get a list of build targets.
First it fails if there were no build done previously. I fixed it by replacing with tools/unix/build_omim.sh -d help.

But anyway the output is >1000 lines of build targets still so not really readable or helpful...
Is it possible to reduce the output to "main" targets only? (I'm new to cmake..)
Or maybe we can compile a short list of really useful targets like desktop, generator_tool, etc.?

[biodranik]

Almost every folder and subfolder is a target. There should be a way to list cmake's high level projects/targets. Documenting is even better.