Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve dev env setup & iOS compilation instructions #647

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Improve dev env setup & iOS compilation instructions #647

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
acc3d21
Improve formatting and phrasing
gy-mate Jan 10, 2025
aa649a0
Update last tested version and folder name; improve style
gy-mate Jan 25, 2025
6f304ef
Put `git clone` commands in fenced code blocks
gy-mate Jan 25, 2025
b062018
Partly revert `repo-configurations` reference; improve wording
gy-mate Jan 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
295 changes: 163 additions & 132 deletions main/docs/technical/build-osmand/how-to-compile-the-ios-version.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,140 +4,171 @@ sidebar_position: 6

# How to Compile the iOS Version

1. First setup the **[development environment](setup-the-dev-environment.md)**.
2. Install Xcode from AppStore (Last tested 14.2)
3. Install Xcode command-line tools
```
$ xcode-select --install
```
Or in case of errors try to download and install it from Apple site: <https://developer.apple.com/download/all/?q=xcode>.

4. Log in into Xcode account (optional)
In case if you don't have Apple Developer account. Open Xcode and go to preferences (via top menu)
```
Preferences -> Accounts
```
Press `+` button. You can log in with your AppleID (login and password from your iOS/macOS devices). Follow Xcode instructions.
For OsmAnd team members: send your AppleID login, so you will be added to to developers list. When you'll get email with invite message activate it.
Close Xcode.

5. Install command-line tools- cmake, svn, cocoapods
```
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
$ brew install svn
$ brew install cmake # tested on 3.25.2, 3.19, 3.11

# for intel
$ sudo gem install cocoapods

# for m1
$ brew install cocoapods
```
6. Download and instal Java jdk 17
```
# for intel
https://download.oracle.com/java/17/archive/jdk-17.0.11_macos-x64_bin.dmg

# for m1
https://download.oracle.com/java/17/archive/jdk-17.0.11_macos-aarch64_bin.dmg
```

7. Create new text file. Or update if it exist.
```
$ mkdir ~/.gradle
$ nano ~/.gradle/gradle.properties
```

Paste this content into it. Save file and restart computer.

```
## Project-wide Gradle settings.
#
# For more details on how to configure your build environment visit
# http://www.gradle.org/docs/current/userguide/build_environment.html
#
# Specifies the JVM arguments used for the daemon process.
# The setting is particularly useful for tweaking memory settings.
# Default value: -Xmx10248m -XX:MaxMetaspaceSize=256m
# org.gradle.jvmargs=-Xmx2048m -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8

org.gradle.daemon=true

org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=2048m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8

#
# When configured, Gradle will run in incubating parallel mode.
# This option should only be used with decoupled projects. More details, visit
# http://www.gradle.org/docs/current/userguide/multi_project_builds.html#sec:decoupled_projects

org.gradle.parallel=true
org.gradle.caching=true

#Fri Apr 08 18:47:31 EEST 2016
# android.useDeprecatedNdk=true
```

8. Run `prepare.sh` to compile Qt library and download external dependencies
```
$ cd ios
$ ./prepare.sh
```

Error: `Xcode not set up properly. You may need to confirm the license...`.
Solution: switch XcodeCommandLineTools to Xcode app, confirm the license and switch it back.
```
$ sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
$ sudo xcodebuild -license accept
$ sudo xcode-select --switch /Library/Developer/CommandLineTools
```

Solution 2: check if xcrun is available: ``` /usr/bin/xcrun -find xcrun ```. If you've got: ``` xcrun: error: unable to find utility "xcrun", not a developer tool or in PATH ```. Then open Xcode > Preferences > Locations and in field "Command Line Tools" select your command line tools "Xcode XX.X" And run `$ ./prepare.sh` again.

Solution 3: Error: `CMake Error ... iphoneos is not an iOS SDK`.
```
$ sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
```

Solution 4: If you've got error like this: ``` CMake Error at CMakeLists.txt:1 (cmake_minimum_required): CMake 3.21.2 or higher is required. You are running version 3.11.2 ```. Then download dmg installer from CMake web site and perfom manual instalation. And run `$ ./prepare.sh` again.
```
https://cmake.org/download/
```

Solution 5: If you've got error like this: ```Failed to configure 'qtbase-ios' for 'ios.simulator.clang.static', aborting...```. Go to folded ```core/external/qtbase-ios/``` and delete all folders starting with ```upstream```. And run `$ ./prepare.sh` again.
1. Set up the **[development environment](setup-the-dev-environment.md)**
Copy link
Author

@gy-mate gy-mate Jan 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Fix grammar
  • Formatting and wording changes

2. Install Xcode from the App Store (the last tested version is `16.2`)
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Update last tested Xcode version to 16.2.

3. Install Command Line Tools for Xcode:

```
$ xcode-select --install
```
Or—in case of an error—try to download and install it from Apple's website: <https://developer.apple.com/download/all/?q=xcode>
Comment on lines +9 to +14
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Formatting and wording changes


4. Log in to Xcode account (optional)

In case you don't have an Apple Developer account.

1. Open Xcode and go to _Preferences_ → _Accounts_ (via the top menu)
2. Press the `+` button. You can log in with your Apple ID (login and password from your iOS/macOS devices). Follow Xcode instructions.
3. _For OsmAnd team members:_ send your Apple ID login, so you will be added to the list of developers. You'll get email with an invite message—activate it.
4. Close Xcode.

Comment on lines -15 to +24
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Break down instructions to steps
  • Formatting and wording changes

5. Install command-line tools: `cmake`, `svn`, `cocoapods`:
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Formatting changes


```
$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
$ brew install svn
$ brew install cmake # tested on 3.25.2, 3.19, 3.11

# for Intel
$ sudo gem install cocoapods

# for Apple silicon
$ brew install cocoapods
Comment on lines -30 to +36
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct chip series' name and capitalization.

```

6. Download and install Java JDK 17

- For Intel-based Macs: <https://download.oracle.com/java/17/archive/jdk-17.0.11_macos-x64_bin.dmg>
- For Apple silicon Macs: <https://download.oracle.com/java/17/archive/jdk-17.0.11_macos-aarch64_bin.dmg>

Comment on lines -36 to +43
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Format links in fenced code blocks as links.

7. Create a new text file or update if it exists:
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Formatting change


```
$ mkdir ~/.gradle
$ nano ~/.gradle/gradle.properties
```

1. Paste this content into it:
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Break down instructions to steps
  • Remove seemingly unnecessary empty lines
  • Formatting changes


```
## Project-wide Gradle settings.
#
# For more details on how to configure your build environment visit
# http://www.gradle.org/docs/current/userguide/build_environment.html
#
# Specifies the JVM arguments used for the daemon process.
# The setting is particularly useful for tweaking memory settings.
# Default value: -Xmx10248m -XX:MaxMetaspaceSize=256m
# org.gradle.jvmargs=-Xmx2048m -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8

org.gradle.daemon=true
org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=2048m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8

# When configured, Gradle will run in incubating parallel mode.
# This option should only be used with decoupled projects. More details, visit
# http://www.gradle.org/docs/current/userguide/multi_project_builds.html#sec:decoupled_projects

org.gradle.parallel=true
org.gradle.caching=true

#Fri Apr 08 18:47:31 EEST 2016
# android.useDeprecatedNdk=true
```

2. Save the file
3. Restart your computer

8. Run `prepare.sh` to compile the Qt library and download external dependencies:

Comment on lines +81 to +82
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Formatting and wording changes

```
$ cd ios
$ ./prepare.sh
```

1. **Error:** `Xcode not set up properly. You may need to confirm the license...`

**Solution 1:** switch _Command Line Tools for Xcode_ to the Xcode app, confirm the license and switch it back:

```
$ sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
$ sudo xcodebuild -license accept
$ sudo xcode-select --switch /Library/Developer/CommandLineTools
```

**Solution 2:** check if `xcrun` is available:

```
/usr/bin/xcrun -find xcrun
```

If you've got `xcrun: error: unable to find utility "xcrun", not a developer tool or in PATH`: open _Xcode → Preferences → Locations_ and in field _Command Line Tools_ select your command line tools _Xcode XX.X_ and run `./prepare.sh` again.

2. **Error:** `CMake Error ... iphoneos is not an iOS SDK`

**Solution:** Run:
```
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
```

3. **Error:** `CMake Error at CMakeLists.txt:1 (cmake_minimum_required): CMake 3.21.2 or higher is required. You are running version 3.11.2`

**Solution:** Download the `.dmg` installer from the CMake website and perfom a manual installation: <https://cmake.org/download/>. Then run `./prepare.sh` again.

4. **Error:** `Failed to configure 'qtbase-ios' for 'ios.simulator.clang.static', aborting...`

**Solution:** Go to folder `core/externals/qtbase-ios` and delete all folders starting with `upstream`. Then run `./prepare.sh` again.
Comment on lines -86 to +119
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Logically restructure & reformat errors and solutions
  • Update external folder name to externals
  • Format link in fenced code blocks as link
  • Further improve formatting



9. Open `osmand.xcworkspace` in Xcode
10. First build.
Set the build target to `OsmAnd Maps`. (Near play/stop buttons). Select as target your device or as one of iOS simulators. But don't use default 'Any iOS Device (arm64)'. Build the project (play button).
11. Troubleshooting - cleaning temp files.
- In case of build errors you can press in Xcode: ```Product -> Clean build folder```
- Close Xcode.
- Delete `baked` and `binaries` folders in `OsmAnd` directory (if it already exists).
- Go to folded ```core/external/qtbase-ios/``` and delete all folders starting with ```upstream```.
- Delete Xcode DerivedData folder: ``` rm -rf ~/Library/Developer/Xcode/DerivedData ```
- Check that all repositories are up to date and on correct branches.
- Restart your computer. (Yes, it can help).
- Then run `$ ./prepare.sh`
- Open XCode and try to build the project again.

12. Troubleshooting (m1 mac)
- In case of ```ld: library not found for -lOsmAndCore_static_standalone```:
- Project Navigator -> OsmAnd_projects -> OsmAnd_projects (in Project/Targets list) -> Build settings -> All -> Architectures -> Excluded Architectures -> Debug
- Add string field of type ```Any IOS Simulator SDK``` with value ```arm64```. (you will need to add it after each prepare.sh run)
- Build project. In case of errors, make all instructions from ```11. Troubleshooting - cleaning temp files.``` and ```prepare.sh``` once again.
10. First build

1. Set the build target to _OsmAnd Maps_ (near Play/Stop buttons)
2. Select your device or one of iOS simulators as the target device. Don't use the default _Any iOS Device (arm64)_!
3. Build the project (Play button)

Comment on lines +123 to +128
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Break down instructions to steps
  • Improve formatting

11. In case of build errors: clean temp files

- Select _Product_ → _Clean Build Folder..._ in Xcode
- Close Xcode
- Delete the `baked` and `binaries` folders in the `OsmAnd` directory (if they exist)
- Go to folder `core/externals/qtbase-ios` and delete all folders starting with `upstream`
- Delete the Xcode `DerivedData` folder:
```
rm -rf ~/Library/Developer/Xcode/DerivedData
```
- Check that all repositories are up to date and on correct branches
- Restart your computer (yes, it can help)
- Run `./prepare.sh`
- Open Xcode and try to build the project again

Comment on lines +129 to +143
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Update external folder name to externals
  • Fix typo
  • Formatting and wording changes

12. **Error:** `ld: library not found for -lOsmAndCore_static_standalone` on Apple silicon Macs

- Open _Project Navigator_ and click on *OsmAnd_projects*
- Click on *OsmAnd_projects* under the _PROJECT_ section
- Open _Build Settings_ → _All_ → _Architectures_ → _Excluded Architectures_ → _Debug_
- Add a string field of type `Any IOS Simulator SDK` with the value `arm64` (you will need to add it after each `./prepare.sh` run)
- Build the project
- In case of errors, follow all instructions in the previous numbered step and run `./prepare.sh` again
Comment on lines +144 to +151
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Restructure and clarify steps
  • Correct chip series' name
  • Formatting and wording changes


13. Kotlin debug addon (optional)
```
$ brew install xcode-kotlin
$ xcode-kotlin install
$ xcode-kotlin sync
```

15. Qt debug addon (optional). If you want to see Qt values in debug mode run this:
```
$ mkdir -p ~/qtlldb
$ git clone https://github.com/gbooker/lldb-qt-formatters ~/qtlldb
$ touch ~/.lldbinit
$ echo "command script import ~/qtlldb/both.py" >> ~/.lldbinit
```
After set this parameters reboot your computer.

Install the Kotlin Native Xcode Plugin for debugging Kotlin code. Run:

```
brew install xcode-kotlin
xcode-kotlin install
xcode-kotlin sync
```
Comment on lines 153 to +161
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Add step description
  • Remove $ from start of lines to make them easier to copy & paste into e.g. Warp


15. Qt debug addon (optional)

If you want to see Qt values in debug mode, run:

```
mkdir -p ~/qtlldb
git clone https://github.com/gbooker/lldb-qt-formatters ~/qtlldb
touch ~/.lldbinit
echo "command script import ~/qtlldb/both.py" >> ~/.lldbinit
```

Then reboot your computer.
Comment on lines -136 to +174
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Remove $ from start of lines to make them easier to copy & paste into e.g. Warp
  • Formatting and wording changes

72 changes: 46 additions & 26 deletions main/docs/technical/build-osmand/setup-the-dev-environment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@
sidebar_position: 4
---

# How to Setup the Development Environment
# How to Set Up the Development Environment


To setup the development environment, you need to install the [repo utility](https://source.android.com/setup/develop#repo) and use the following [repo manifest](https://github.com/osmandapp/OsmAnd-manifest/blob/master/readonly.xml) or [any other configuration](https://github.com/osmandapp/OsmAnd-manifest).
To set up the development environment, you need to install the [`repo` utility](https://source.android.com/setup/develop#repo) and use the following [`repo` manifest](https://github.com/osmandapp/OsmAnd-manifest/blob/master/readonly.xml) or [any other configuration](https://github.com/osmandapp/OsmAnd-manifest).
Comment on lines -5 to +8
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Fix grammar
  • Formatting changes



If you plan to use the `readonly.xml` and the `repo` utility you can run the following:
Expand All @@ -15,27 +15,47 @@ repo init -u https://github.com/osmandapp/OsmAnd-manifest -m readonly.xml
repo sync
```

You can also use just git and checkout the following git repositories to correct folder names:
* Folder **android** - **[Osmand](https://github.com/osmandapp/Osmand.git)**
* ```git clone https://github.com/osmandapp/Osmand.git android```
* Folder **ios** - **[OsmAnd-ios](https://github.com/osmandapp/OsmAnd-ios.git)**
* ```git clone https://github.com/osmandapp/OsmAnd-ios.git ios```
* Folder **resources** - **[OsmAnd-resources](https://github.com/osmandapp/OsmAnd-resources.git)**
* ```git clone https://github.com/osmandapp/OsmAnd-resources.git resources```
* Folder **core** - **[OsmAnd-core](https://github.com/osmandapp/OsmAnd-core.git)**
* ```git clone https://github.com/osmandapp/OsmAnd-core.git core```
* Folder **help** - **[osmandapp.github.io](https://github.com/osmandapp/osmandapp.github.io.git)**
* ```git clone https://github.com/osmandapp/osmandapp.github.io.git help```
* Folder **core-legacy** - **[OsmAnd-core-legacy](https://github.com/osmandapp/OsmAnd-core-legacy.git)**
* ```git clone https://github.com/osmandapp/OsmAnd-core-legacy.git core-legacy```
* Folder **build** - **[OsmAnd-build](https://github.com/osmandapp/OsmAnd-build.git)**
* ```git clone https://github.com/osmandapp/OsmAnd-build.git build```
* Folder **tools** - **[OsmAnd-tools](https://github.com/osmandapp/OsmAnd-tools.git)** (servers, map creation)
* ```git clone https://github.com/osmandapp/OsmAnd-tools.git tools```
* Folder **web** - **[web](https://github.com/osmandapp/web.git)** (web-only)
* ```git clone https://github.com/osmandapp/web.git web```
* Folder **misc** - **[OsmAnd-misc](https://github.com/osmandapp/OsmAnd-misc.git)** (standalone utilities)
* ```git clone https://github.com/osmandapp/OsmAnd-misc.git misc```


You might not need all repositories to get tools / android or ios working. You can always double check corresponding branches in [repo-configurations](https://github.com/osmandapp/OsmAnd-manifest).
You can also use just `git` and checkout the following `git` repositories to their correct folder names:
* Folder `android` – **[Osmand](https://github.com/osmandapp/Osmand.git)**:
```
git clone https://github.com/osmandapp/Osmand.git android
```
* Folder `ios` – **[OsmAnd-ios](https://github.com/osmandapp/OsmAnd-ios.git)**:
```
git clone https://github.com/osmandapp/OsmAnd-ios.git ios
```
* Folder `resources` – **[OsmAnd-resources](https://github.com/osmandapp/OsmAnd-resources.git)**:
```
git clone https://github.com/osmandapp/OsmAnd-resources.git resources
```
* Folder `core` – **[OsmAnd-core](https://github.com/osmandapp/OsmAnd-core.git)**:
```
git clone https://github.com/osmandapp/OsmAnd-core.git core
```
* Folder `help` – **[osmandapp.github.io](https://github.com/osmandapp/osmandapp.github.io.git)**:
```
git clone https://github.com/osmandapp/osmandapp.github.io.git help
```
* Folder `core-legacy` – **[OsmAnd-core-legacy](https://github.com/osmandapp/OsmAnd-core-legacy.git)**:
```
git clone https://github.com/osmandapp/OsmAnd-core-legacy.git core-legacy
```
* Folder `build` – **[OsmAnd-build](https://github.com/osmandapp/OsmAnd-build.git)**:
```
git clone https://github.com/osmandapp/OsmAnd-build.git build
```
* Folder `tools` – **[OsmAnd-tools](https://github.com/osmandapp/OsmAnd-tools.git)** (servers, map creation):
```
git clone https://github.com/osmandapp/OsmAnd-tools.git tools
```
* Folder `web` – **[web](https://github.com/osmandapp/web.git)** (web-only):
```
git clone https://github.com/osmandapp/web.git web
```
* Folder `misc` – **[OsmAnd-misc](https://github.com/osmandapp/OsmAnd-misc.git)** (standalone utilities):
```
git clone https://github.com/osmandapp/OsmAnd-misc.git misc
```


Comment on lines +18 to +60
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Formatting changes

You might not need all repositories to get `tools`, `android` or `ios` working, just the ones described in the [`repo` configurations'](https://github.com/osmandapp/OsmAnd-manifest) XML files.
Copy link
Author

@gy-mate gy-mate Jan 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Update reference
  • Formatting and wording changes