Build scripts to create a white-label application on Platform.Bible

Platform.Bible is an extensible Bible translation software. Its functionality is provided almost completely by extensions in order to be very powerful and flexible, giving developers the freedom to create and to share their desired Bible translation experience.

This repository only contains build scripts for creating a white-label application built on Platform.Bible. It does not contain the code for Platform.Bible or any extensions. Please see paranext-core if you are looking to develop extensions on Platform.Bible.

Note: Platform.Bible and its official releases are at paranext-core. As this repository is currently configured, running these build scripts just creates a Platform.Bible application with the wrong version number and some additional sample extensions bundled in. You must fork this repository and configure it to your needs in order for it to do something useful.

This software is not yet ready for users. We'll update here with where you can install it when it is ready.

If you would still like to try Platform.Bible, you can download early releases here on GitHub.

To use .AppImage files in Linux, install FUSE (you only need to do this once), for example, on Ubuntu (>= 22.04):

sudo apt install libfuse2

Then simply execute/run the .AppImage file, which you can download from Releases.

If you download and run the ARM release of Platform.Bible from a computer running Apple Silicon, you will likely encounter a warning from Apple's Gatekeeper stating that "Platform.Bible is damaged and can't be opened. You should move it to the Trash." or something very similar:

Unfortunately, this is the message Apple chose to display for ARM applications that are not signed (including Platform.Bible since we have not yet set up application code signing on Mac).

If you trust Platform.Bible and would like to run it even though it is not code signed, you will need to run the following terminal command every time you install a new version of Platform.Bible:

xattr -c /Applications/Platform.Bible.app

xattr -c clears all attributes on the provided file. Running this command removes all attributes on the currently-installed Platform.Bible application file including the quarantine flag Gatekeeper puts on unsigned ARM applications downloaded from the internet.

Note: The following development pre-requisite instructions are a duplicate of those found in paranext-core's Developer Install section. If you encounter issues, please refer to that section for the most up-to-date instructions on satisfying development pre-requisites.

Set up pre-requisites for building:

Add the system libraries needed for Electron, Build Instructions (Linux).

macOS doesn't come preinstalled with all the icu4c libraries. They must be installed separately to provide Unicode support to our .NET code. Platform.Bible is configured to expect those libraries to be installed using MacPorts. The icu package on MacPorts has the icu4c libraries needed for icu.net to run properly.

The build processes are configured to automatically download and package icu4c libraries with the application, but for development this has to be done manually.

The .NET data provider is configured to automatically copy the icu4c dylibs into its build output directory. If for some reason you need to disable that, you will need to set an environment variable for the OS to find them. For example:

export DYLD_FALLBACK_LIBRARY_PATH="$HOME/lib:/usr/local/lib:/usr/lib:/opt/local/lib"

If you need to set environment variables like the above, consider adding them to your .zprofile so you don't have to remember to do it manually.

Install Node.js version >=18.0.0 (18.0.0 or greater is required for using fetch). We recommend using Volta.

Install dotnet .NET 8 SDK from here.

To check if dotnet is installed run (ensure you have a v8 SDK):

dotnet --version
dotnet --list-sdks

Clone the repo and install dependencies:

git clone https://github.com/paranext/paranext.git
cd paranext
npm install

Note: these instructions are for adjusting the application created by this repository that white-labels Platform.Bible. Please see paranext-core if you are looking to develop extensions on Platform.Bible.

This repository focuses primarily on modifying files found in a "core" repository containing Platform.Bible code as well as other repositories containing extensions for Platform.Bible then packaging them together to create an application that white-labels Platform.Bible and bundles in additional extensions.

Warning: Building this application involves cloning and building multiple other repositories. This may take up to 5 GB (as of 7/23/24) of disk space total.

In order to prepare this repository for building your application or modifying the repositories involved in building your application, you must run the following command:

npm run reset-and-patch

This command clones the repositories involved in building your application into temp-build (if necessary), resets and pulls them to their latest revision (including deleting untracked files), and patches them with the patches contained in repo-patches. Once you run this command, you are ready to modify the repositories as desired.

Note: you can also run this command to reset the files in the repositories back to the latest saved repo patches if you made modifications that you do not want to save.

If you want to make edits to the repositories involved in building your application, you can do so in two ways:

productInfo.json contains information about your application including which extension repositories to bundle into your application, values to replace in the "core" application like name and version, and more. Edit these values to adjust which repositories are involved in the build and how the final build comes out.

Note: if you change the repositories linked in your productInfo.json, you will need to re-run npm run reset-and-patch to clone the new repositories.

Each repository involved in building your application may be git patched in order to modify the contents of the repository to suit your needs. After running npm run reset-and-patch, open their local clones in temp-build and make edits and new files as desired. You can optionally refer to values in productInfo.json by specifying {{ productInfo.<key> }} in the temp-build code, and it will be replaced with the appropriate value when building the application. See temp-build/paranext-core/assets/localization/en.json for an example.

Note: you can only refer to values that are direct keys of the top-level object in productInfo.json like productInfo.productName. You cannot refer to deeper values like productInfo.build.coreRepo.uri (please file an issue if you need to be able to do this). Also note you can refer to values that exist in models/product-info.schema.json but are not necessarily present in productInfo.json like productInfo.name because they are filled in if they are not present (see lib/product-info.data.ts). You can also specify additional properties not found in the schema like productInfo.someOtherThing and use them if desired.

Once you have adjusted productInfo.json to your liking and have made edits to the repos in temp-build, you can run the following command to save your repo patch changes (including untracked files):

npm run save-repo-patches

Alternatively, if you would like to save your repo patch changes and build the application (or if you just want to build the application after running npm run reset-and-patch without making any changes), you can run the following command to save and build:

npm run save-and-build

Note: due to the way the build scripts work, you must save repo patches before building to make sure you do not make unintentional changes to your patches. Alternatively, if you prefer to clear out all changes and untracked files since the patches were last saved and built, you can do so by running different commands.

If you do not want to do any development but just want to build the application without modifying the build in any way, you can run the following:

npm run build-ci

This will destroy any changes and untracked files you have made to the repositories in temp-build, so please be sure to do this only after saving or if you want to reset changes. This will also leave your temp-build folder in an in-between state that needs to be cleaned or reset. Please proceed to [run npm run reset-and-patch](#preparing-the-repositories-for-patching) if you want to modify the application or run the following command to clean out temp-build` if you want to remove temporary build files completely:

npm run clean

This will also destroy any changes and untracked files you have made to the repositories in temp-build, so please be sure to do this only after saving or if you want to reset changes.

1. Create a branch of the form release/*, e.g. release/v1.2.3, or release/v1.2.3-rc1.
2. Update the version in your project's package.json (and productInfo.json if it has a separate version number), e.g.:

   npm version 1.2.3

3. Create a new draft GitHub Release. Ensure the following are included:
   • a Tag version, e.g. v1.2.3, choose Create new tag on publish.
   • set the Target to the release branch.
   • a copy of the change log. Click Generate release notes as a starting point.
   • Click Save draft.
4. Update CHANGELOG.md with changes in this release from the GitHub draft Release.
5. Commit these changes to your release branch and push the commit to GitHub.
6. Once the GitHub build Action has finished, it will add build artifact files to the draft release. Remove the .blockmap files and leave the .yml files and the installers and executable, e.g. .exe on Windows.
7. Publish the release on GitHub.
8. Merge the release branch back into main with a merge commit.

If you run commands that patch the repositories and encounter an error like the following (? at the end of each line):

error: while searching for:
$color--platform-bible: #a70e13;?
$color--paratext-bible: #89ae26;?
?
$color--pt9-lightgreen: #b8d432;?
$color--pt9-darkgreen: #3f511e;?
$color--pt9-darkgray: #4c4c4c;?
?
$color--text: #191919;?
$color--text-dimmed: #aaa;?

error: patch failed: src/renderer/styles/_vars.scss:2
error: src/renderer/styles/_vars.scss: patch does not apply

This likely means you are on Windows and are encountering conflicts due to line ending differences. For these patches to succeed, you should be using LF line endings, not CRLF. Please ensure your patch files and all files they are targeting are using LF line endings, and try patching again.

If your GitHub Actions are failing because they cannot access private GitHub repositories, you need to configure a fine-grained Personal Access Token with permissions to clone from the private GitHub repositories:

1. Create a new fine-grained Personal Access Token with the following Read permissions for the private repositories to clone (source):

   • Commit statuses
   • Contents
   • Pull requests
   • Metadata

2. Add the new personal access token as a Repository Secret called READ_REPOS_TOKEN

If Git unexpectedly asks for your username and password while running builds, it is likely trying to clone private GitHub repositories via HTTPS which is not configured on your computer. If you want to provide your username and password to Git, feel free to do so. If you prefer to use SSH authentication with GitHub, you need to change the uris for the private repos in productInfo.json to point to the SSH uris for those repos.

You can use Volta with this repo to use the right version of tools such as node and npm.

If you don't use Volta just look at the volta property in package.json to see the right tool versions to install in your preferred way.

MIT © SIL International