June 26, 2022

Building White Star

Macintosh

These instructions are for building White Star 28.9.* and newer and assumes you want to build the latest release.

Prerequisites

Getting the source

The White Star source code is available from GitHub along with the Unified XUL Platform source code is available from Pale Moon.

These instructions assume you are going to create a directory in your home directory (~) called whitestar-source. You can, of course, put the source code anywhere you want as long as the path does not contain any spaces.

Using git

This is the simplest method and git is bundled with Xcode.

Using the source archives

This requires downloading the source archive from the DBSoft site and is more complicated:

The following is not recommended for Machintosh. However, if you obtain the source archives in a non-tar form, e.g. zip or 7z, then you will have to correct file permissions on the source tree.

chmod -R 744 whitestar-source

Build dependencies

Install MacPorts

Install the required build dependencies by executing the following commands:

port install autoconf213
port install yasm

# If your MacOS is missing python or it is too old
port install python27

Build instructions

Configure

Create a file called .mozconfig in the source folder you cloned or unpacked the source to. Make sure it contains at least the following for a close-to-official build:

.mozconfig file

# Standard build options for White Star
ac_add_options --enable-application=whitestar
ac_add_options --enable-optimize=-O2
ac_add_options --enable-jemalloc
ac_add_options --enable-strip
ac_add_options --enable-devtools
ac_add_options --disable-eme
ac_add_options --disable-webrtc
ac_add_options --disable-gamepad
ac_add_options --disable-tests
ac_add_options --disable-debug
ac_add_options --disable-necko-wifi
ac_add_options --disable-updater
ac_add_options --with-macos-sdk=/Path/to/SDKs/MacOSX10.11.sdk
ac_add_options --with-branding=whitestar/branding/whitestar

# Uncomment if using clang++ from Xcode 10 or higher
# export CXX="/usr/bin/clang++ -std=gnu++11 -stdlib=libc++"

Note: LESS IS MORE! There are some pre-made build configs out there that have a lot of options listed, often with insane resulting build configurations. Do not use those and stick to the instructions here.

Build

Start the build:

./mach build

Be patient. Building could take a long time. Your Mac will be fully occupied compiling and linking the browser (you can expect 100% CPU usage throughout and lots of memory use - provide ample cooling) and you should not be using it for anything else that is resource-intensive at this time. Especially memory-intensive applications should be avoided because it can cause issues with the linker (memory fragmentation) resulting in a very unstable browser.

Strip/package

After building is completed, you can take the resulting binaries for a test run in the object directory directly (see the on-screen instructions at the end of the build process) but it will not be complete yet. You need to strip and package the browser to integrate additional code, pack up the resource files, and have a ready-to-use browser. You do this by running:

./mach package
This will create a properly packaged disk image in your object folder under the White Star source folder. e.g. for Mac 64bit:
~/whitestar-source/obj-x86_64-apple-darwin{kernel-version}/dist/whitestar-{version}.mac64.dmg