paranext-core

Extensible Bible translation software

Summary

Platform.Bible is 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 contains the core Platform.Bible software (Electron client, extension host including "PAPI", and .NET library) and the extensions that come bundled with it. There are many other repositories containing additional extensions.

Users

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 it, you can download early releases here on GitHub.

Linux Users

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.

Mac Users

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 it:

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.

Developer Install

Set up pre-requisites for building:

Linux Development Pre-requisites

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

macOS Development Pre-requisites

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.

All Platforms Development Pre-requisites

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

Cloning and installing dependencies (all platforms)

Clone the repo and install dependencies:

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

To build the declaration type file papi.d.ts for extensions to use, run the following:

npm run build:types

Starting Development

Start the app in the dev environment:

npm start

After you run npm start (or, in VSCode, launch Debug Paranext Core), you can edit the code, and the relevant processes will hot reload.

Developing Extensions

Paranext Core extensions are found in the extensions folder. Please follow the instructions in extensions/README.md to develop extensions.

Please see the Extension Template wiki for guides on developing extensions.

GitHub Pages

Platform.Bible API Documentation

• Explore the declarations of types available on the PAPI.

Platform.Bible React Components and Hooks Documentation

• Check out the React components and hooks available to use.

Platform.Bible Utilities Documentation

• Check out the utility functions, types, and classes available to use.

JavaScript Tool Manager

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.

Packaging for Production

To package apps for the local platform:

npm run package

Publishing

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 release/app/package.json, e.g.:

   cd ./release/app
   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.

Testing

The following tests run automatically on each GitHub PR (see test.yml).

To run C# unit tests:

cd c-sharp-tests
dotnet test

To run C# unit tests watching for file changes:

cd c-sharp-tests
dotnet watch test

To run all TS unit tests:

npm test

To run an individual TS unit test watching for file changes:

npm test -- <path/to/test-file.test.ts> --watch

You can also use the recommended VS Code extensions to run tests there.

Storybook

To run Storybook locally:

npm run storybook

To build Storybook:

npm run storybook:build

To run Storybook as a web app, after it was built successfully:

npx http-server ./storybook-static

Windows Development with WSL2

On Windows, you can install WSL (Windows Subsystem for Linux) so you can test cross-platform compatibility on Linux (as well as Windows). You'll need to use a Linux distribution with WSL2 (rather than WSL1) so the X-Server windows can be opened for Electron.

1. Here is how to install Linux on Windows with WSL.
2. You'll want to follow that by setting up to use VS Code, Git and NodeJS with WSL. See the various tutorials.
3. In the WSL distribution, add system libraries needed for Electron, see Linux Development Pre-requisites above.
4. In the WSL distribution, clone the repo as described above under Developer Install.

You'll be running a copy of the repo in both Windows and WSL so make sure they are both up-to-date.

You can use VS Code from your host to access code in your WSL repo clone using the Microsoft Remote Development VS Code extension.

VS Code Extension Options

Extensions highly recommended for this repo are already displayed in VS Code through the Extensions Recommendations settings. These are optional extensions that our developers enjoy using:

• TODO Highlight
• Version Lens

Formatting and Linting

Formatting happens automatically when you commit. If you use VS Code with this repo's recommended extensions it will format when you save.

To check TypeScript for readability, maintainability, and functionality errors, and to check a few other files for proper formatting, run the following from the repo root (or just use VS Code with this repo's recommended extensions)

npm run format
npm run lint

To check C# for readability, maintainability, and functionality errors, run the following from the repo root (or just use VS Code with this repo's recommended extensions)

cd c-sharp
dotnet tool restore
dotnet csharpier .

Documentation in papi.d.ts

VSCode renders JSDoc comments in the UI to make it easier for developers to use functions and properties as intended. However, those comments do not always propagate from modules to the d.ts type definition file when those modules are re-exported. To help with this problem in papi.d.ts that we export for extensions to reference, we added some custom functionality.

If you want comments to be copied from one location in papi.d.ts to another, do the following:

• In the JSDoc comments that you want copied elsewhere, add "JSDOC SOURCE myServiceName" (must have a blank line after) in the JSDoc comments like this:

/**
 * JSDOC SOURCE myService
 *
 * myService is amazing. Here are more details about it.
 * ...
 */
const myService = {
  ...
}

• In the location where you want the docs copied, add "JSDOC DESTINATION myServiceName" like this:

const papi = {
  ...
  /** JSDOC DESTINATION myService */
  myService,

Thanks

Some important decisions in this project were inspired by the work done in Visual Studio Code. Thanks VS Code developers for some great ideas!

License

MIT © SIL International