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.

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.

We can produce snap packages available on the snap store for users to run our software on Linux. Once you have all the snap tools installed for your flavor of Linux, run sudo snap install <snap name> or sudo snap install <snap name> --channel=edge for our most recent, pre-release build that has passed our limited, automated testing suite.

To install a locally created snap package, run the following commands:

sudo snap install <path to snap file> --dangerous
sudo snap connect <snap name>:dot-<snap name>

Some users may find that not everything works properly in Linux without some additional setup. Please see How to set up Platform.Bible on Linux for more information.

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 an app downloaded from the Internet. Are you sure you want to open it?":

Don't be alarmed! This is a typical warning, seen when downloading most apps from the Internet. It also says "Apple checked it for malicious software and none was detected." If you trust Platform.Bible and would like to run it select "Open."

Once the app is opened, you may see a dialog that says "Platform.Bible wants to use your confidential information stored in 'Platform.Bible Safe Storage' in your keychain."

We use encryption to keep your data safe, allowing access to keychain provides encryption services with papi.dataProtection so extensions can store user data securely. If you approve of this, please allow keychain access.

In addition to the core extensions that are included with Platform.Bible, developers can create other extensions for use in Platform.Bible or any white-label product based on it. Extensions can either be bundled with a product or installed individually by users. Please see Extension Template wiki for guides on developing additional extensions.

A white-label product based on Platform.Bible will typically include custom extensions beyond those bundled with Platform.Bible itself. To develop such extensions, you will need to make a separate repo with those extensions. See Modifying productInfo.json for more information about bundling extensions into your product.

Extensions that are not bundled can be made available for users to install. See Running your extension in an app for installation information.

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 prerequisites.

Set up prerequisites 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 or Homebrew.

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.

Use the icu package on MacPorts.

Use the icu4c package on Homebrew.

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

This repository is forked from paranext, which is periodically updated to reflect changes in Platform.Bible that affect white-labeling. We recommend you periodically update your repository by merging in the latest paranext template updates.

To set up this repository to be updated from the template, run the following command once after cloning it:

git remote add template https://github.com/paranext/paranext

To update this repository from the template, first make sure the current (checked-out) branch of your local repository has no working changes. Then run the following commands:

git fetch template
git merge template/main --allow-unrelated-histories

Note: The merge/squash commits created when updating this repository from the template are important; Git uses them to compare the files for future updates. If you edit this repository's Git history, please preserve these commits (do not squash them, for example) to avoid unnecessary merge conflicts in the future.

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 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.

These steps will walk you through releasing a version on GitHub and bumping the version to a new version so future changes apply to the new in-progress version.

1. In each repository in your productInfo.json, create a release for the version you want to include in this repo's release. Then, set branch for each repo listed in productInfo.json to the tag corresponding to the release of that repo you want to include in this release. DO NOT leave branch as any kind of Git ref that can change like a branch name. Otherwise, you will not be able to determine later exactly what code is included in the release.

2. Make sure this repo's package.json version is on the version number you want to release. If it is not, manually dispatch the Bump Versions workflow or run the bump-versions npm script to set the version to what you want to release on the branch you want to release from.

3. Manually dispatch the Publish workflow in GitHub Actions targeting the branch you want to release from. This workflow creates a new pre-release for the version you intend to release and creates a new bump-versions-<next_version> branch to bump the version after the release so future changes apply to a new in-progress version instead of to the already released version. This workflow has the following inputs:

   • version: enter the version you intend to publish (e.g. 0.2.0). This is simply for verification to make sure you release the code that you intend to release. It is compared to the version in the code, and the workflow will fail if they do not match.
   • newVersionAfterPublishing: enter the version you want to bump to after releasing (e.g. 0.3.0-alpha.0). Future changes will apply to this new version instead of to the version that was already released. Leave blank if you don't want to bump
   • bumpRef: enter the Git ref you want to create the bump versions branch from, e.g. main. Leave blank if you want to use the branch selected for the workflow run. For example, if you release from a stable branch named release-prep, you may want to bump the version on main so future development work happens on the new version, then you can rebase release-prep onto main when you are ready to start preparing the next stable release.
   • uploadReleaseAssets: whether to upload the release assets to Amazon S3. If false, the release will still be created in GitHub, but no assets will be uploaded to S3. In order to successfully upload the release assets to S3, you need to set up some secrets and variables.

4. In GitHub, adjust the new draft release's body and other metadata as desired, then publish the release.

5. Open a PR and merge the newly created bump-versions-<next_version> branch.

6. When appropriate, in Snapcraft, promote the newly uploaded release to the appropriate channel.

If you want to upload your release assets to Amazon S3 when running the Publish workflow, you need to set up an AWS access key and then configure some repository secrets and repository variables in GitHub:

1. Create an AWS access key for a user with the following permissions:

   • s3:* on the S3 bucket where the release assets should be uploaded and the files in the directory in which to put the release assets (see below for more information). There are likely narrower permissions you can set and still successfully upload the release assets.

2. Set up the following repository secrets and variables

   • Repository secrets:
     • AWS_S3_RELEASE_ACCESS_KEY_ID: The access key ID for authenticating with AWS
     • AWS_S3_RELEASE_SECRET_ACCESS_KEY: The secret access key for authenticating with AWS
   • Repository variables:
     • AWS_S3_RELEASE_BUCKET_NAME: The name of the S3 bucket where the release assets should be uploaded
     • AWS_S3_RELEASE_DIRECTORY: The directory in which to put the release build directories. The builds themselves will be in $AWS_S3_RELEASE_DIRECTORY/$RELEASE_VERSION/$RUNNER_OS/

Note: you can very likely use other levels of secrets and variables like organization-level, but this has not been tested.

Sometimes, it may be useful to change the version without publishing a release.

To bump versions without publishing a release, manually dispatch the Bump Versions workflow in GitHub Actions targeting the branch on which you want to change versions. Alternatively, you can run the bump-versions npm script. This workflow will create a branch named bump-versions-<version> from the target branch (or, if running the script, your current head) with the needed changes. Open a PR and merge that new branch into the branch on which you want to change versions.

This workflow has the following inputs:

• newVersion: enter the version you want to bump to (e.g. 0.3.0-alpha.0). Future changes will apply to this new version instead of to the version.
• newMarketingVersion: a human-readable "marketing-level" version to call this version. It is best to set this only on the specific commit you intend to release so there is no confusion over which version is running. E.g. β1
• newMarketingVersionMoniker: a human-readable "marketing-level" version moniker to call this version. It is best to set this only on the specific commit you intend to release so there is no confusion over which version is running. E.g. Developer Preview

For example, to bump branch my-branch to version 0.2.0 with optional marketing version β1 and optional marketing version moniker Developer Preview, run the following:

git checkout my-branch
npm run bump-versions -- 0.2.0 --marketing-version β1 --marketing-version-moniker "Developer Preview"

Then create a PR and merge the bump-versions-0.2.0 branch into my-branch. my-branch is now ready for release.

Following are some problems you may encounter while publishing and steps to solve them.

If you see the following error in the GitHub Actions workflow logs while packaging:

Module build failed (from ./node_modules/swc-loader/src/index.js):
Error: Failed to load native binding

Please see "Failed to load native binding" in the Troubleshooting guide for how to solve this problem.

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 you for credentials while running builds, it is likely trying to clone private GitHub repositories via HTTPS which is not configured on your computer. You have a few options to resolve this issue:

• If it is not installed yet, install git-credential-manager. Then, run the build again, and it will open a browser to the GitHub website for you to log in. The website will pass an authorization code to Git (OAuth). git-credential-manager comes bundled with Git in some installation methods.
  • We have not tested installing git-credential-manager separately from Git and logging in with it, so please let us know if you try this method.
• Provide your username and a personal access token to Git.
• 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.

If you want your Windows installer to be signed by a certificate so it is trusted by Windows, you need to obtain a certificate from a trusted certificate provider like digicert. If you use digicert specifically, then you can add the following secrets to your repo in GitHub and uncomment the Code signing - Windows block in publish.yml:

• WIN_CERTIFICATE_SHA1_HASH
• WIN_CODE_SIGNING_CERT_HOST
• WIN_CODE_SIGNING_CERT_HOST_API_KEY
• WIN_CODE_SIGNING_CLIENT_CERT
• WIN_CODE_SIGNING_CLIENT_CERT_PASSWORD
• WIN_CODE_SIGNING_KEYPAIR_ALIAS

If you use a certificate provider other than digicert, you will need to add a step to your publishing workflow that handles the signing process used by that certificate provider. The commented out step in publish.yml will only work with digicert certificates.

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.

This project is licensed under the MIT License. Copyright © 2022-2025 SIL Global and United Bible Societies