[docs] Dedup and improve Getting Sources section #1551
156
docs/INSTALL.md
|
|
@ -1,9 +1,69 @@
|
|||
# Building
|
||||
|
||||
- [Getting sources](#getting-sources)
|
||||
- [Desktop](#desktop-app)
|
||||
- [Android](#android-app)
|
||||
- [iOS](#ios-app)
|
||||
|
||||
## 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.
|
||||
|
||||
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
|
||||
|
||||
```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.
|
||||
pastk
commented
I don't see a way how to make it elegant and easy to read unless its duplicated... E.g. imagine in INSTALL we'd have
And in the CONTRIB
Not good as people will forget to substitute their github name in the clone command. or
Better, but requires a reader to jump back-and-forth between the two docs still. And if we'll add e.g. options to reduce download size (from below) to CONTRIB and cross-reference them to INSTALL then it'll become more ugly even. Maybe I just didn't get your idea right though. I don't see a way how to make it elegant and easy to read unless its duplicated...
E.g. imagine in INSTALL we'd have
> If you're planning to contribute your changes then read CONTRIB first.
> Clone the repo:
> `git clone ....`
And in the CONTRIB
> Fork the repo first and then follow instructions in INSTALL to clone it.
Not good as people will forget to substitute their github name in the clone command.
or
> Fork the repo first and then clone it
> `git clone <forked-repo>...`
> Follow instructions in INSTALL#configure to configure the cloned repo.
Better, but requires a reader to jump back-and-forth between the two docs still.
And if we'll add e.g. options to reduce download size (from below) to CONTRIB and cross-reference them to INSTALL then it'll become more ugly even.
Maybe I just didn't get your idea right though.
To avoid duplication, we can write in INSTALL that use this To avoid duplication, we can write in INSTALL that use this `git clone …` if you just want to build it for yourself and save disk space, or that `git clone…` if you want to contribute.
And then start CONTRIBUTING with "Please follow INSTALL.md steps first". And then start CONTRIBUTING with "Please follow INSTALL.md steps first".
|
||||
|
||||
Clone the main repository (~5.5Gb):
|
||||
|
||||
```bash
|
||||
git clone 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.
|
||||
|
Move to contribute block. But is it really necessary? If you want to contribute, then cloning everything is the most reliable way. s/form/from/ Move to contribute block. But is it really necessary? If you want to contribute, then cloning everything is the most reliable way.
s/form/from/
pastk
commented
Its not necessary of course, its just a way to lower barriers for people with low-spec machines and limited/slow Internet. E.g. my laptop's SSD is 120Gb, devoting 30+Gb to be able to contribute to OM is a lot. Though I agree those options could be moved somewhere in footnotes or a special subsection perhaps. Its not necessary of course, its just a way to lower barriers for people with low-spec machines and limited/slow Internet.
E.g. my laptop's SSD is 120Gb, devoting 30+Gb to be able to contribute to OM is a lot.
Cloning the full repo took me an hour almost and I was lucky to have an unlimited wifi for that - usually I'm on a limited plan.
Though I agree those options could be moved somewhere in footnotes or a special subsection perhaps.
Why 30+ GB? My full checked-out repo takes ~9GB (7GB .git folder). Every Android arch debug build takes an additional 4.5Gb. Building a desktop-only app takes also a few GBs, depending on the configuration. Why 30+ GB? My full checked-out repo takes ~9GB (7GB .git folder). Every Android arch debug build takes an additional 4.5Gb. Building a desktop-only app takes also a few GBs, depending on the configuration.
pastk
commented
30+Gb is a minimum total that also includes android studio, sdk, ndk, etc. On my system it looks like this:
There I have a small emulator image without Google services and a quite old low-mem emulated device (Nexus S) and just a 256Mb emulated SD. With a more conventional option it'll be a couple Gb more. So actually if we expect someone to just follow default instructions and build for all 3 arches (which is by default) then it comes close to 40Gb... 30+Gb is a minimum total that also includes android studio, sdk, ndk, etc.
On my system it looks like this:
> 1.6 android studio
> 8.5 full repo
> 9 sdk, ndk, emulator image
> 1.5 ~/.android/avd (emulated storage etc?)
> = 20.5Gb
>
> +1.5 ~./gradle/caches
> +4.5*3=13.5 build files for 3 arches
> = 35.5Gb total
There I have a small emulator image without Google services and a quite old low-mem emulated device (Nexus S) and just a 256Mb emulated SD. With a more conventional option it'll be a couple Gb more.
So actually if we expect someone to just follow default instructions and build for all 3 arches (which is by default) then it comes close to 40Gb...
Interesting. We probably need to document a "low space" options, e.g. installing only JDK without Android Studio (or reusing a system one), building release instead of debug to save some space, mounting a compressed NDK image :) But let's start focusing on systems with enough free space first and make it an easy start for these environments. Interesting. We probably need to document a "low space" options, e.g. installing only JDK without Android Studio (or reusing a system one), building release instead of debug to save some space, mounting a compressed NDK image :)
But let's start focusing on systems with enough free space first and make it an easy start for these environments.
|
||||
|
||||
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.
|
||||
|
Let's put it into the clone cmd together with --recurse-submodules. The install doc should show the simplest and the fastest way to build and run. All dev details can be stored in contributing doc. What do you think? Let's put it into the clone cmd together with --recurse-submodules.
The install doc should show the simplest and the fastest way to build and run. All dev details can be stored in contributing doc. What do you think?
pastk
commented
I understand your idea of separating contribution and installation docs. For the reference, at the moment
I think its possible to separate but it'll mean a lot of duplication, basically the bulk of current How do we define a build/run-only env? For that case I think there is no need for Android Studio and actually the fastest way to get the repo would be shallow/partial clone as it reduces download times drastically. I'd rather prefer the current approach with a detailed doc that gives a default/straightforward way of doing things alongside some options so the one following it can make decisions on the go. A compromise would be to hide most of the optional things in e.g. footnotes or a separate subsection so that the "default way" is more clear. Please let me know your further thoughts on this! I understand your idea of separating contribution and installation docs.
For the reference, at the moment `CONTRIBUTING.md` says:
> Code Contributions
>
> Please follow instructions in INSTALL.md to set up your development environment. Create and submit a Pull Request with your changes.
I think its possible to separate but it'll mean a lot of duplication, basically the bulk of current `INSTALL.md` would be moved to `CONTRIBUTING.md` and then `INSTALL.md` simplified.
How do we define a build/run-only env? For that case I think there is no need for Android Studio and actually the fastest way to get the repo would be shallow/partial clone as it reduces download times drastically.
I'd rather prefer the current approach with a detailed doc that gives a default/straightforward way of doing things alongside some options so the one following it can make decisions on the go.
A compromise would be to hide most of the optional things in e.g. footnotes or a separate subsection so that the "default way" is more clear.
Please let me know your further thoughts on this!
Current docs are hard for newcomers. It would be great if there will be an "easy and fast" way to compile and run the app on Android, iOS, and Desktops. Also, ideally, if someone wants to make a very simple code change/fix, it should also be very easy and clear. And in parallel, there could be a very detailed doc for those who want to get all details. I don't know how to better organize it. Any ideas are welcome. Current docs are hard for newcomers. It would be great if there will be an "easy and fast" way to compile and run the app on Android, iOS, and Desktops. Also, ideally, if someone wants to make a very simple code change/fix, it should also be very easy and clear. And in parallel, there could be a very detailed doc for those who want to get all details.
I don't know how to better organize it. Any ideas are welcome.
Maybe make starting INSTALL sections simple, but move all details to sections below? And insert some links to them to avoid duplication? Maybe make starting INSTALL sections simple, but move all details to sections below? And insert some links to them to avoid duplication?
pastk
commented
Yeap I agree it should be simple and newbie-friendly. Yeap I agree it should be simple and newbie-friendly.
I'll try to re-arrange!
|
||||
|
||||
Go into the cloned repo:
|
||||
```bash
|
||||
cd organicmaps
|
||||
```
|
||||
|
||||
Clone git submodules (~3Gb):
|
||||
|
It can be done in the clone command. Let's simplify it. It can be done in the clone command. Let's simplify it.
|
||||
|
||||
```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:
|
||||
|
||||
```bash
|
||||
./configure.sh
|
||||
```
|
||||
|
||||
**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`):
|
||||
|
||||
```bash
|
||||
./configure.sh <private-repo-name>
|
||||
```
|
||||
|
||||
## Desktop app
|
||||
|
||||
### Preparing
|
||||
|
|
@ -53,36 +113,6 @@ sudo dnf install -y \
|
|||
brew install cmake qt@5
|
||||
```
|
||||
|
||||
### Getting sources
|
||||
|
||||
Clone the repository:
|
||||
|
||||
```bash
|
||||
git clone --recursive https://github.com/organicmaps/organicmaps.git
|
||||
```
|
||||
|
||||
Default clone destination directory is organicmaps.
|
||||
|
||||
Update git submodules (sometimes doesn't work automatically):
|
||||
|
||||
```bash
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
Configure the repository as opensource build:
|
||||
|
||||
```bash
|
||||
./configure.sh
|
||||
```
|
||||
|
||||
or with private repository
|
||||
|
||||
```bash
|
||||
./configure.sh <private-repo-name>
|
||||
```
|
||||
|
||||
You can check usage `./configure.sh --help`
|
||||
|
||||
### Building
|
||||
|
||||
With all tools installed, just run `tools/unix/build_omim.sh`.
|
||||
|
|
@ -247,46 +277,6 @@ export JAVA_HOME=*A-PATH-TO-YOUR-ANDROID-STUDIO-INSTALLATION*/android-studio/jre
|
|||
export JAVA_HOME=*A-PATH-TO-YOUR-ANDROID-STUDIO-INSTALLATION*/Contents/jre/Contents/Home
|
||||
```
|
||||
|
||||
### Getting sources
|
||||
|
||||
**Windows 10.** Enable [symlinks][git-symlinks] support in git:
|
||||
|
||||
[git-symlinks]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-coresymlinks
|
||||
|
||||
```bash
|
||||
git config --global core.symlinks true
|
||||
```
|
||||
|
||||
Clone the repository:
|
||||
|
||||
```bash
|
||||
git clone --recursive https://github.com/organicmaps/organicmaps.git
|
||||
```
|
||||
|
||||
Update git submodules (sometimes doesn't work automatically):
|
||||
|
||||
```
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
Configure the repository as opensource build:
|
||||
|
||||
```bash
|
||||
./configure.sh
|
||||
```
|
||||
|
||||
or with private repository
|
||||
|
||||
```bash
|
||||
./configure.sh <private-repo-name>
|
||||
```
|
||||
|
||||
**Windows 10.** Use WSL to run `./configure.sh`:
|
||||
|
||||
```bash
|
||||
bash ./configure.sh # execute the script by using Ubuntu WSL VM
|
||||
```
|
||||
|
||||
**Windows 10.** Alternative way is to initialize Boost manually:
|
||||
|
||||
1. Install Visual Studio 2019 Community Edition.
|
||||
|
|
@ -360,32 +350,6 @@ Install [Xcode](https://apps.apple.com/ru/app/xcode/id497799835?mt=12) from AppS
|
|||
|
||||
Enroll in the [Apple Developer Program](https://developer.apple.com/programs/) (you can run Organic Maps in Simulator without this step).
|
||||
|
||||
### Getting sources
|
||||
|
||||
Clone the repository:
|
||||
|
||||
```bash
|
||||
git clone --recursive https://github.com/organicmaps/organicmaps.git
|
||||
```
|
||||
|
||||
Update git submodules (sometimes doesn't work automatically):
|
||||
|
||||
```
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
Configure the repository as opensource build:
|
||||
|
||||
```bash
|
||||
./configure.sh
|
||||
```
|
||||
|
||||
or with private repository
|
||||
|
||||
```bash
|
||||
./configure.sh <private-repo-name>
|
||||
```
|
||||
|
||||
### Configuring Xcode
|
||||
|
||||
Set up your developer account and add certificates:
|
||||
|
|
|
|||
Maybe move this to CONTRIBUTE and reference it here?