{"id":13545573,"url":"https://github.com/kiwix/kiwix-apple","last_synced_at":"2025-05-15T14:04:23.175Z","repository":{"id":36314363,"uuid":"40619002","full_name":"kiwix/kiwix-apple","owner":"kiwix","description":"Kiwix for iOS \u0026 macOS","archived":false,"fork":false,"pushed_at":"2025-05-08T17:17:01.000Z","size":30159,"stargazers_count":572,"open_issues_count":41,"forks_count":82,"subscribers_count":24,"default_branch":"main","last_synced_at":"2025-05-09T16:42:48.148Z","etag":null,"topics":["ios","kiwix","macos","offline","swift","wikipedia"],"latest_commit_sha":null,"homepage":"https://apple.kiwix.org","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kiwix.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"Support/Assets.xcassets/AppIcon.appiconset/1024-mac.png","governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"kiwix","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2015-08-12T19:05:29.000Z","updated_at":"2025-05-06T22:26:03.000Z","dependencies_parsed_at":"2023-09-27T06:24:38.860Z","dependency_job_id":"1486739d-afb3-4b23-b8ed-790bc8b83932","html_url":"https://github.com/kiwix/kiwix-apple","commit_stats":null,"previous_names":["kiwix/kiwix-apple","kiwix/apple"],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwix%2Fkiwix-apple","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwix%2Fkiwix-apple/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwix%2Fkiwix-apple/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwix%2Fkiwix-apple/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kiwix","download_url":"https://codeload.github.com/kiwix/kiwix-apple/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254337612,"owners_count":22054253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ios","kiwix","macos","offline","swift","wikipedia"],"created_at":"2024-08-01T11:01:05.953Z","updated_at":"2025-05-15T14:04:23.133Z","avatar_url":"https://github.com/kiwix.png","language":"Swift","funding_links":["https://github.com/sponsors/kiwix"],"categories":["Swift","Media","ios","swift"],"sub_categories":["Content"],"readme":"\u003ca href=\"https://apps.apple.com/us/app/kiwix/id997079563\" target=\"_blank\" align=\"left\"\u003e\n  \u003cimg src=\"https://developer.apple.com/assets/elements/badges/download-on-the-app-store.svg\" alt=\"Download on the app store\" height=\"40\" /\u003e\n\u003c/a\u003e\n\n-----\n\n# Kiwix for Apple iOS \u0026 macOS\n\nKiwix is an offline reader for Web content, primarily designed to make [Wikipedia](https://www.wikipedia.org/) available offline. It reads archives in the [ZIM](https://openzim.org) file format, a highly compressed open format with additional metadata.\n\nThis is the Apple version of Kiwix, supporting iOS and macOS.\n\n[![CodeFactor](https://www.codefactor.io/repository/github/kiwix/kiwix-apple/badge)](https://www.codefactor.io/repository/github/kiwix/kiwix-apple)\n[![CI Build Status](https://github.com/kiwix/kiwix-apple/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/kiwix/kiwix-apple/actions/workflows/ci.yml?query=branch%3Amain)\n[![CD Build Status](https://github.com/kiwix/kiwix-apple/actions/workflows/cd.yml/badge.svg?branch=main)](https://github.com/kiwix/kiwix-apple/actions/workflows/cd?query=branch%3Amain)\n[![Codecov](https://codecov.io/gh/kiwix/kiwix-apple/branch/main/graph/badge.svg)](https://codecov.io/gh/kiwix/kiwix-apple)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n\u003cimg src=\"https://img.shields.io/badge/Swift-5.9-orange.svg\" alt=\"Drawing=\"/\u003e\n[![Join Slack](https://img.shields.io/badge/Join%20us%20on%20Slack%20%23kiwix--apple-2EB67D)](https://slack.kiwix.org)\n\n## Download\n\nKiwix apps are made available primarily via the [App Store](https://ios.kiwix.org) and [Mac App Store](https://macos.kiwix.org). macOS version can also be [downloaded directly](https://download.kiwix.org/release/kiwix-desktop-macos/kiwix-desktop-macos.dmg).\n\nMost recent versions of Kiwix support the three latest major versions of the\nOSes (either iOS or macOS). Older versions of Kiwix being still\ndownloadable for older versions of macOS and iOS on the Mac App Store.\n\n## Known bugs\n\n* ZIM files including video content work only properly from Kiwix\n  version `3.4.0`, from iOS/iPadOs `17.0` and from macOS `14.0`. With\n  older versions of Kiwix or OSes, videos might work, but the full\n  support is not guaranted and bugs won't be investigated further. The\n  reasons behind this is the lack (only recent) support of open video\n  formats used in the ZIM files.\n\n## Develop\n\nKiwix developers usually work with latest macOS and Xcode. Check our [Continuous Integration Workflow](https://github.com/kiwix/kiwix-apple/blob/main/.github/workflows/ci.yml) to find out which Xcode version we use on Github Actions.\n\n### Get started\n\nTo get started, you will need the following:\n\n* An [Apple Developer account](https://developer.apple.com) (doesn't require membership)\n* [Xcode](https://developer.apple.com/xcode/) installed\n* Its command-line utilities (`xcode-select --install`)\n* [Homebrew](https://brew.sh) installed\n\n### Steps\n 1) clone this repository\n 2) from the project folder **run the following command: `brew bundle`**\n\n### Xcode settings\n\nTo compile and run Kiwix from Xcode locally, you will need to:\n* Change the Bundle Identifier (in *Signing \u0026 Capabilities*)\n* Select appropriate Signing Certificate/Profile.\n* It is recommended to enable:\n\n`Xcode settings \u003e Text Editing \u003e Editing`\n\u003e \"While Editing\":\n\u003e - ✅ \"Automatically trim trailing whitespace\"\n\u003e - ✅ \"Include whitespace-only lines\"\n\n### Dependencies installed for you\nOur `Brewfile` will install all the necessary dependencies for you:\n- our `CoreKiwix.xcframework` ([libkiwix](https://github.com/kiwix/libkiwix) and [libzim](https://github.com/openzim/libzim)) - the version of which is specified in the `Brewfile`\n- [XcodeGen](https://github.com/yonaskolb/XcodeGen) which will create the project files for you\n\n### How XcodeGen is working?\nXcode 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`).\n\nThis means, that you can work in Xcode as usual, but you don't need to worry about the project file changes anymore.\n\nContributors: please note, **changes to the Xcode project folder will not be tracked by git**.\n\nIf you wish to change any settings as part of your contribution, please **edit the `project.yml` file instead.**\n\nPlease refer to the [XcodeGen documentation](https://github.com/yonaskolb/XcodeGen) for further details.\n\n### CPU Architectures\n\nKiwix compiles on both macOS architectures x86_64 and arm64 (Apple silicon).\n\nKiwix for iOS and macOS can run, in both cases, on x86_64 or arm64.\n\n### Switch to another version of the `CoreKiwix.xcframework`\n\n`CoreKiwix.xcframework` is published with all supported platforms and CPU architectures:\n\n- [latest release](https://download.kiwix.org/release/libkiwix/libkiwix_xcframework.tar.gz)\n- [latest nightly](https://download.kiwix.org/nightly/libkiwix_xcframework.tar.gz): using `main` branch of both `libkiwix` and `libzim`.\n\nIn 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.\n\n#### Compiling `CoreKiwix.xcframework`\n\nYou may want to compile it yourself, to use different branches of said projects for instance.\n\nThe xcframework is a bundle of all libkiwix dependencies for multiple architectures\nand platforms. The `CoreKiwix.xcframework` will contain libkiwix\nlibrary for macOS archs and for iOS. It is built off [kiwix-build\nrepo](https://github.com/kiwix/kiwix-build).\n\nMake sure to preinstall kiwix-build prerequisites (ninja and meson). If you use homebrew, run the following\n\n```sh\nbrew install ninja meson\n```\n\nMake sure Xcode command tools are installed. Make sure to download an\niOS SDK if you want to build for iOS.\n\n```sh\nxcode-select --install\n```\n\nThen you can build `libkiwix`\n\n```sh\ngit clone https://github.com/kiwix/kiwix-build.git\ncd kiwix-build\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -e .\n\nkiwix-build --config apple_all_static libkiwix\n# assuming your kiwix-build and apple folder at at same level\ncp -r BUILD_apple_all_static/INSTALL/lib/CoreKiwix.xcframework ../apple/\n```\n\nYou can now launch the build from Xcode and use the iOS simulator or\nyour macOS target. At this point the xcframework is not signed.\n\n\n### Debug webviews\n\nIn development builds (run from Xcode) it is possible to debug the\nweb-views via Safari development menu.\n\nIf Kiwix iOS runs on a device (iPhone or iPad), you need to connect\nthe device to your macOS device via an USB cable.\n\nIf Kiwix for macOS or iOS runs in simulator it will work out of the box\nin this regard.\n\nFor a detailed explanation of the web-development mode, please see\nApple's documentation:\nhttps://developer.apple.com/documentation/safari-developer-tools/inspecting-ios\n\n## Deployment\n\n### Nightly to FTP\n\nEach night at 01:32 am CET, we build the Kiwix iOS and macOS apps.  These\nare developer signed builds, notarized (a process required to install\nthem outside of the app store) and uploaded to our [nightly\nfolder](https://download.kiwix.org/nightly/). The files are versioned\nusing the current date.\n\n### Weekly to TestFlight\n\nEach Monday at 02:00 am CET, if there were code changes within the\nlast week (any git commits to main), we publish Kiwix for iOS and\nmacOS to [Testflight](https://testflight.apple.com/).  These are\nAppStore builds, using the current app version from code (see\n`project.yml`).\n\n### On-demand TestFlight\n\nIt is also possible to trigger\n[Testflight](https://testflight.apple.com/) builds - on-demand - by\ntagging `testflight` any revision of the code base. You reuse the very\nsame tag for consequent testflight releases. This will run the same\nprocess as the \"weekly\" Testflight (we just do not need to wait up to\nMonday).\n\n### Releasing to AppStore and FTP\n\nOnce satisfied with the quality of the app in TestFlight, we can\nproceed with the Kiwix release process.\n\nThe release process is triggered by a [GitHub\nRelease](https://github.com/kiwix/kiwix-apple/releases). This process\ncreates new testflight builds, and only these should be sent to\napproval to Apple. The same release process also creates and publishes the\nmacOS DMG to our [file server](https://download.kiwix.org/release/kiwix-macos/).\nOnce the app is approved by Apple, they can be made available to the public\non the App Store.\n\nIn case the app is rejected by Apple in a way that requires a new\nbuild to fix the issue, a new patch release should be prepared and\nreleased... and re-submitted to App Store.\n\n### Last step\n\nIf all that is done, we should create a PR, incrementing the version\nnumber of the project (see: `project.yml`), and the deployment cycle\ncan start again.\n\n## Reporting a bug\n\n* Bug reports and features requests should be done [online](https://github.com/kiwix/kiwix-apple/issues).\n* Follow [issue reporting good\n  practices](https://github.com/kiwix/overview/blob/main/REPORT_BUG.md).\n* On macOS - if requested by a maintainer - pack your Kiwix app\n  container with the following command (then make it available\n  somewhere online): `tar -czvf ~/Documents/self.Kiwix.tgz\n  ~/Library/Containers/self.Kiwix`.\n\n## Support\nIf you're enjoying using Kiwix, drop a ⭐️ on the repo!\n\n## License\n\n[GPLv3](https://www.gnu.org/licenses/gpl-3.0) or later, see\n[LICENSE](LICENSE) for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiwix%2Fkiwix-apple","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkiwix%2Fkiwix-apple","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiwix%2Fkiwix-apple/lists"}