Building and Releasing

Building and Releasing
- MacOS
- Windows

MacOS

The process on MacOS is split into two parts: building the .app directory (build_pcxg_MacOS.sh) and releasing it (bundling it into an installer and signing the result, sign_pcxg_MacOS.sh). The release script (release_pcxg_MacOS.sh) runs the build and signing scripts consecutively.

To test modifications to Portable-CELLxGENE, it is sufficient to run the build script (build_pcxg_MacOS.sh) and not release the output.

Building

The conda environment should be updated with a new version number (and copyright years if necessary) in the modified_cellxgene_gateway version of CELLxGENE-Gateway (available here). This information is stored in version_number.js and copyright.js within cellxgene_gateway/static/js, respectively. The conda environment should then be created and packaged into a .tar.gz archive using create_conda_env_pcxg_conda_env_MacOS_arm64.sh and create_conda_env_pcxg_conda_env_MacOS_x64.sh (for Apple-silicon and Intel-based processors, respectively). These tar.gz archives should be uploaded to the Portable-CELLxGENE-assets repository.

The Portable-CELLxGENE.app template is also required, available here. Unzip this file, then, in Finder, right-click on the extracted .app directory and select Show Package Contents. Edit Contents/Info.plist in Xcode (right-click -> Open with -> Xcode) and update the version number (and copyright years if necessary).

Once both the conda environment has been built and archived as a .tar.gz and the template .app directory has been downloaded and updated, build_pcxg_MacOS.sh can be run. It require the paths to:

The conda environment .tar.gz;
The template .app directory;
The launch_cellxgene.sh script.

sh build_pcxg_MacOS.sh ./path/to/conda/environment ./path/to/template.app ./path/to/launch_cellxgene.sh

The build process will produce a .app directory with the conda environment packaged inside.

Signing

The output of the build process can be signed with the signing script. This only needs to be done for a release of the software: it is not necessary when building Portable-CELLxGENE for testing purposes.

The signing script should be run in the directory containing the outputs of the build script. it requires the name of an app-specific password for notarytool and the name of the Developer ID Application certificate that you want to use.

sh sign_pcxg_MacOS.sh ./path/to/dmg_background.png "name of app-specific password for notarytool" "Developer ID Application: Team Name (Team ID)"

The signing script will output a .dmg disk image that has been signed and notarized to allow easy installation.

Releasing (building + signing)

The building and signing steps can be run consecutively using release_pcxg_MacOS.sh.

sh release_pcxg_MacOS.sh \
    ./path/to/conda/environment \
    ./path/to/template.app \
    ./path/to/launch_cellxgene.sh \
    ./path/to/dmg_background.png \
    "name of app-specific password for notarytool" \
    "Developer ID Application: Team Name (Team ID)"

The release script will store its outputs in a new directory called Portable_CELLxGENE_Build_Dir_ appended with a timestamp of when the script was executed. This will contain the .app and .dmg generated by the above scripts.

Windows

Download and extract the latest pack of build assets from here. Once extracted, the folder should contain two directories:

 windows_build_assets
 ├── app
 │   ├── Portable-CELLxGENE.bat
 │   └── favicon.ico
 └── install
     ├── Install-Portable-CELLxGENE-Windows.ps1
     └── installer_favicon.ico

Download and extract the latest Windows conda environment from here.
Build the app’s .exe. To do this, compile Portable-CELLxGENE.bat into a .exe using the bat2exe tool. You should be able just to point this tool to the windows_build_assets\app directory and it will take care of the rest.
Sign the .exe produced in the previous step using signtool. signtool sign /tr http://timestamp.sectigo.com /td sha256 /fd sha256 /a Portable-CELLxGENE-Windows.exe
Zip together the signed .exe and the conda environment from Step 2 and upload to the assets repo.
Build the installer using the ps2exe tool in PowerShell. Sign the .exe it outputs. Note that you may need to update the download path used by the script to point to the new bundle created in Step 5. ps2exe -inputFile .\Install-Portable-CELLxGENE-Windows.ps1 -iconFile .\installer_favicon.ico -noConsole -exitOnCancel signtool sign /tr http://timestamp.sectigo.com /td sha256 /fd sha256 /a Install-Portable-CELLxGENE-Windows.exe
Upload the installer .exe to the main github repo.