From a7736376df835604729670b0ac0ad4ab78cb4a38 Mon Sep 17 00:00:00 2001 From: Balazs Perlaki-Horvath Date: Tue, 9 Jan 2024 00:28:35 +0100 Subject: [PATCH] Add contribution readme for technical steps --- CONTRIBUTION.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 CONTRIBUTION.md diff --git a/CONTRIBUTION.md b/CONTRIBUTION.md new file mode 100644 index 0000000..e70f0ae --- /dev/null +++ b/CONTRIBUTION.md @@ -0,0 +1,112 @@ +# Technical documentation for contributors + +## Brand vs app +The name of the brand, is defined as a subfolder. +To clarify things, we have 2 platforms for our apps: iOS and macOS. +Therefore each brand will end up with 2 apps (one for iOS and one for macOS). + +## At the beginning we have the following: +- custom brand folders, each with an info.json file, and xcassets +- we have the kiwix/apple code (as a seperate repository). + + We do not add any swift code to custom apps. All swift code related to custom apps is already included in kiwix/apple repository, it is just "not used" in the Kiwix apps. + +The `kiwix/apple` repo is checked out into `/apple` folder, while the custom app repo (this one), is checked out under `/custom` folder. + +Since most of the code and files are already in the `/apple` folder, we copy the `/custom` folder under it, so it ends up in: `/apple/custom`. We do the rest of the building from that folder. + +## What we need in order to build a custom app? + +### A Zim file +This needs to be downloaded from the url given in the `info.json`, and placed under the branded folder, eg: `/custom/dwds` + +### A .plist file +The plist file is a list of settings, that is used by xcode for the given target to be built. It is in a required xml format. + +It is created under the folder with the same name, eg.: `dwds/dwds.plist` + +It should contains the following common variables: +``` +APP_STORE_ID = ${APP_STORE_ID} +CUSTOM_ABOUT_TEXT = ${CUSTOM_ABOUT_TEXT} +CUSTOM_ABOUT_WEBSITE = ${CUSTOM_ABOUT_WEBSITE} +CUSTOM_ZIM_FILE = ${CUSTOM_ZIM_FILE} +SETTINGS_DEFAULT_EXTERNAL_LINK_TO = ${SETTINGS_DEFAULT_EXTERNAL_LINK_TO} +``` + +as a matter of fact these key/values are going to be the same for each brand. The final value for these are defined in the relevant .xcconfig files. + +The plist file should also contain the following variables that have their value inlined (with example values here): +``` +CUSTOM_ABOUT_WEBSITE = "https://www.dwds.de" +SETTINGS_SHOW_EXTERNAL_LINK_OPTION = false +SETTINGS_SHOW_SEARCH_SNIPPET = false +``` + +Since the plist files are pretty much the same, +and we want to reflect any changes made in the main (kiwix/apple) repo as well, creating them is done in the following steps: + +1) we make a copy of the `Support/Info.plist` file contained in the main repo (kiwix/apple) -> `Custom.plist` +2) we add all the common variables to it. This is done by using the macOS built in commandline tool named `usr/libexec/PlistBuddy`. Note that the plist file expects not only the keys and values, but the type of the variable as well (which we do not have in our custom `info.json` file). Currently we use string and boolean types. +3) we make a copy of this `Custom.plist` into the custom folder eg: -> `dwds/dwds.plist` +4) we add the custom values for this brand, using the same tool `PlistBuddy` mentioned above + +This way we end up with a plist file dedicated to a specific brand containing all the variables and values it needs. + +### An xcconfig file +Under the custom app folder we create a branded +xcconfig file, eg: `dwds/dwds.xcconfig`, it is containing brand specific (build time) values, it should have the following (with example values): +``` +CUSTOM_ABOUT_TEXT = Für Schreibende, Lernende, Lehrende und Sprachinteressierte:... +APP_STORE_ID = id6473090365 +SETTINGS_DEFAULT_EXTERNAL_LINK_TO = alwaysLoad +SETTINGS_SHOW_EXTERNAL_LINK_OPTION = False +SETTINGS_SHOW_SEARCH_SNIPPET = False +CUSTOM_ZIM_FILE = dwds_de_dictionary_nopic_2023-12-15 +``` + +## Enforced language? +If we use enforcing a language for a brand, what that really means is: we cannot use any of the localization folders contained in the main (kiwix/apple) repo, instead we need to make a copy of a single language folder, eg: `de.lproj` and place it into the custom folder eg: `/custom/dwds/de.lproj` and include only that in the project. + +(Note: only including / excluding does not work as the references to those language folders in the final Xcode project file will mess up. So we need a copy of the folder, and only this way it works as expected.) + +An extra step is required here, we also need to set the DEVELOPMENT_LANGUAGE to this value (eg. "de"). + +# A new custom_project.yml file +The main `kiwix/apple` repo contains a `project.yml` file, it describes all the common build and project settings, and all the templates we re-use to create a final xcode project file, which is used to build the custom apps. At the end each custom app will be a separate target we can build. +Therefore we need dynamically create the `custom_project.yml` file, which will import the `project.yml`, and sets up the new targets (one for each brand), it looks more or less, like this: +``` +include: +- project.yml +targets: + dwds: + templates: + - ApplicationTemplate + configFiles: + Debug: custom/dwds/dwds.xcconfig + Release: custom/dwds/dwds.xcconfig + settings: + base: + DEVELOPMENT_LANGUAGE: de + INFOPLIST_FILE: custom/dwds/dwds.plist + INFOPLIST_KEY_CFBundleDisplayName: DWDS + INFOPLIST_KEY_UILaunchStoryboardName: SplashScreen.storyboard + MARKETING_VERSION: 2023.12.3 + PRODUCT_BUNDLE_IDENTIFIER: org.kiwix.custom.dwds + sources: + - path: custom/dwds + - path: custom/SplashScreen.storyboard + destinationFilters: + - iOS + - path: Support + excludes: + - '*.xcassets' + - Info.plist + - '**/*.lproj' +``` +Once this is ready, we can call `xcodegen` on it: +```xcodegen -s custom_project.yml``` which will create the `Kiwix.xcodeproj`, and that will contain the original `Kiwix` target and all the branded targets as well eg. `dwds`. + +## A splash screen +The splash screen file is going to be the same for each custom app (it is using a branded logo image from the branded xcassets). As you can see from the above example, this file's final location is going to be: `/apple/custom/SplashScreen.storyboard`. +