This is the home for Kiwix apps for Apple iOS and macOS.
Kiwix apps are made available primarily via the App Store and Mac App Store. macOS version can also be downloaded directly.
Most recent versions of Kiwix support the three latest major versions of the OSes (either iOS or macOS). Older versions of Kiwix being still downloadable for older versions of macOS and iOS on the Mac App Store.
Kiwix developers usually work with latest macOS and Xcode. Check our Continuous Integration Workflow to find out which Xcode version we use on Github Actions.
To get started, you will need the following:
- An Apple Developer account (doesn't require membership)
- Xcode installed
- Its command-line utilities (
xcode-select --install) - Homebrew installed
- clone this repository
- from the project folder run the following command:
brew bundle
To compile and run Kiwix from Xcode locally, you will need to:
- Change the Bundle Identifier (in Signing & Capabilities)
- Select appropriate Signing Certificate/Profile.
- It is recommended to enable:
Xcode settings > Text Editing > Editing
"While Editing":
- ✅ "Automatically trim trailing whitespace"
- ✅ "Include whitespace-only lines"
Our Brewfile will install all the necessary dependencies for you:
- our
CoreKiwix.xcframework(libkiwix and libzim) - the version of which is specified in theBrewfile - XcodeGen which will create the project files for you
Xcode project files are not directly contained within this repository, instead they are generated for you automatically (as git hooks on post-merge, post-checkout, post-rewrite - see the .pre-commit-config.yaml).
This means, that you can work in Xcode as usual, but you don't need to worry about the project file changes anymore.
Contributors: please note, changes to the Xcode project folder will not be tracked by git.
If you wish to change any settings as part of your contribution, please edit the project.yml file instead.
Please refer to the XcodeGen documentation for further details.
Kiwix compiles on both macOS architectures x86_64 and arm64 (Apple silicon).
Kiwix for iOS and macOS can run, in both cases, on x86_64 or arm64.
CoreKiwix.xcframework is published with all supported platforms and CPU architectures:
- latest release
- latest nightly: using
mainbranch of bothlibkiwixandlibzim.
In order to use another version of CoreKiwix, than the one pre-installed, you can simply replace the CoreKiwix.xcframework folder at the root of the project with the version downloaded, and unpacked.
You may want to compile it yourself, to use different branches of said projects for instance.
The xcframework is a bundle of all libkiwix dependencies for multiple architectures
and platforms. The CoreKiwix.xcframework will contain libkiwix
library for macOS archs and for iOS. It is built off kiwix-build
repo.
Make sure to preinstall kiwix-build prerequisites (ninja and meson). If you use homebrew, run the following
brew install ninja mesonMake sure Xcode command tools are installed. Make sure to download an iOS SDK if you want to build for iOS.
xcode-select --installThen you can build libkiwix
git clone https://github.com/kiwix/kiwix-build.git
cd kiwix-build
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
kiwix-build --target-platform apple_all_static libkiwix
# assuming your kiwix-build and apple folder at at same level
cp -r BUILD_apple_all_static/INSTALL/lib/CoreKiwix.xcframework ../apple/You can now launch the build from Xcode and use the iOS simulator or your macOS target. At this point the xcframework is not signed.
Each night 01:32 am CET, we build our iOS and macOS apps. These are developer signed builds, notarized (a process required to install them outside of the app store) and uploaded to our FTP nightly folder. The files are versioned using the current date.
Mondays at 02:00 am CET, we build our apps, but only if there were code changes within the last week (any git commits to main).
These are AppStore builds, which are uploaded to TestFlight, using the current app version from code (see project.yml).
It is also possible to create TestFlight builds on-demand, by pushing a git tag starting with "testflight" to the repo. This will run the same process as the "weekly" build (we just do not need to wait a whole week).
Once we are happy with the quality of the app in TestFlight, we can send it for approval to Apple. Once approved by Apple, we can release them to the AppStore. At the same time, we do want to release our macOS app via FTP as well. For this, we run our "Post App Release" workflow, which can be triggered by creating a Github Release, based on the git commit used for the TestFlight apps (the ones that were approved by Apple). The specific commit that triggered the (now approved) TestFlight app, can be found under Github Actions. This Github Release (based on this specific commit) will rebuild the macOS application and upload it to FTP to the release folder. Again, the purpose of this is to make the very same macOS app - which was released to the AppStore - also available via FTP.
If all that is done, we should create a PR, incrementing the version number of the project (see: project.yml), and the deployment cycle can start again.
- Bug reports and features requests should be done online.
- Follow issue reporting good practices.
- On macOS - if requested by a maintainer - pack your Kiwix app
container with the following command (then make it available
somewhere online):
tar -czvf ~/Documents/self.Kiwix.tgz ~/Library/Containers/self.Kiwix.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent