Building Pale Moon: Microsoft Windows

These instructions are for building Pale Moon 31.0.0 and newer and assumes you want to build the latest release.

Prerequisites

At least Windows 10 64-bit (32-bit build environments or Windows versions < 10 are not supported)
Microsoft Visual Studio 2022 (Community Edition (free) or Pro/Paid version -- Express won't work).
We're assuming you're using the Community Edition for this document.
Select the following components during install:
- "Desktop development with C++"
- "Game development with C++".
- Verify you have also selected "Windows 11 SDK 10.0.26100.0" in the right pane under "Installation details".
You may also want to consider installing the IDE in a different location with a shorter path, but please do leave the SDK paths to default when you do (only change the top option).
Screenshot for clarity.
MozillaBuild 3.4 (4.0+ is not recommended as it relies on recent Mozilla changes for clang building and won't work for MSVC out of the box!).
This is an all-in-one build package with software licensed under various Open Source and permissive licenses. See the individual components in the package after extraction for details.
At least 6 GB RAM (8 GB or more strongly recommended, especially if building with parallel tasks)
Plenty of free disk space
Recommended: coffee or tea

Important note: If you are planning to build 32-bit binaries with Visual Studio 17.4 or later and plan to run on older hardware, there is currently a known compiler/runtime issue leading to browser instability, that you need to work around by using an older version of the compiler and runtimes.
In this case you need to go into "individual components" of the Visual Studio installer, and select the following components in addition:

MSVC v143 - VS 2022 C++ x64/x86 build tools (v14.33-17.3) (Out of Support)
C++ 14.33 (17.3) ATL for v143 build tools (x86 & x64) (Out of support)
C++ 14.33 (17.3) ATL for v143 build tools with Spectre mitigations (x86 & x64) (Out of support)
C++/CLI support for v143 build tools (x86 & x64) (Out of support)
C++ 14.33 (17.3) MFC for v143 build tools with Spectre mitigations (x86 & x64) (Out of support)
Windows 11 SDK (10.0.22621.0)

You will be warned this is not fully supported. You will also need additional build configuration to point to the correct tools; see below.

Getting the source

These instructions will assume you are going to create a directory on your C drive called palemoon-source. You can, of course, put the source code anywhere you want as long as the path does not contain any spaces.

Using git

Git is the official way to get the Pale Moon source code from our repository server and to build.

Install git and open a Git Bash prompt, and change directory to the desired source location, e.g.
```
cd /location-you-picked/palemoon-source/
```

Execute the following commands:

git clone https://repo.palemoon.org/MoonchildProductions/Pale-Moon.git ./
git submodule init && git submodule update
git checkout release && git submodule update

Close Git Bash and proceed to the "Build instructions" below.

Using the source archives

These instructions are for building Pale Moon 29.4.1 to 29.4.6 as well as older versions that were released as source code snapshot archives.

This requires downloading source archives from the Pale Moon Archive Server:

Navigate to the source directory on the Archive Server and download the desired version of the source tarball.
The archive filename is in the following format (where n.n.n is the Pale Moon version):
```
palemoon-n.n.n-source.tar.xz
```
Extract the source code to the desired location.
Proceed to the "Build instructions" below.

Build instructions

Configure

Create a file called .mozconfig in the source folder you cloned or unpacked the source to.

(Yes, that is {dot}mozconfig -- don't omit the . at the start. Also make sure it's not .mozconfig.txt or something crooked like that. If you are hiding extensions of known file types, fix that first in folder options because it's a PITA when trying to do this kind of thing)

Alternatively: Create a text file with any name (e.g. myconfig.txt) and issue the command

export MOZCONFIG=/path/to/myconfig.txt

in the build shell prompt before issuing any

mach

commands.

Make sure it contains at least the following for a close-to-official build excluding updater:

.mozconfig file

# Tell the build system if we're building 64-bit.
# Set this to `BUILD_64=` for 32-bit, leave as-is for default 64-bit
BUILD_64=1

# Processor architecture specific build options
if [ -n "$BUILD_64" ]; then
  BUILD_ARCH=x64
  ac_add_options --target=x86_64-pc-mingw32
  ac_add_options --host=x86_64-pc-mingw32
else
  BUILD_ARCH=x86
fi

# Automatically clobber if CLOBBER was touched
mk_add_options AUTOCLOBBER=1

# Application and target
ac_add_options --enable-application=palemoon

# Build options
# Adjust the -j parameter if you need more or fewer parallel build tasks
# Maximum supported without build errors is around 32, and it's recommended to set this to 
# number of cores in your CPU -2
mk_add_options MOZ_MAKE_FLAGS="-j8"
ac_add_options --enable-optimize="-O2 -GTs -GS- -Qspectre -utf-8"

# Please see https://www.palemoon.org/redist.shtml for restrictions when using the official branding.
ac_add_options --enable-official-branding
export MC_OFFICIAL=1
export MOZILLA_OFFICIAL=1

# Only enable the internal updater if you supply automatic update infrastructure
# and have configured the relevant preferences in your branding!
ac_add_options --enable-update-channel=release
ac_add_options --disable-updater

# Enabling this only offers marginal benefits on first start and may not work on own builds
ac_add_options --disable-precompiled-startupcache

ac_add_options --enable-jemalloc
ac_add_options --enable-strip

ac_add_options --disable-parental-controls
ac_add_options --disable-accessibility
ac_add_options --disable-gamepad
ac_add_options --disable-webrtc

ac_add_options --enable-av1
ac_add_options --enable-jxl

WIN32_REDIST_DIR="C:/{{VCINSTALLDIR}}/VC/redist/MSVC/14.42.34433/$BUILD_ARCH/Microsoft.VC143.CRT"
WIN_UCRT_REDIST_DIR="C:/Program Files (x86)/Windows Kits/10/Redist/10.0.26100.0/ucrt/DLLs/$BUILD_ARCH"

Replace {{VCINSTALLDIR}} with the folder where you installed Visual Studio (use forward slashes!)
Replace 14.40.33807 and 10.0.26100.0 in the redist dir paths to match the version of the compiler and SDK you installed as part of MSVC.

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.

Note: Please check the Visual C++ redist directories. When using MozillaBuild 3.0 or later, $VCINSTALLDIR will not be defined and you will have to indicate a full path. If you build with a different Win SDK version (e.g. the one included with VS2022 or an earlier/later version -- not recommended) or have installed the SDK in a different path than the default, then you need to adjust the mozconfig path to the UCRT DLLs accordingly.

Note: You need additional configuration for building 32-bit on VS 17.4 or later! You will specifically need the following at the end of your mozconfig for 32-bit builds:

# Hack required for Win32 so it won't crash on old hardware.
export CC=C:/{{VCINSTALLDIR}}/VC/Tools/MSVC/14.33.31629/bin/HostX64/x86/cl.EXE
export LD=C:/{{VCINSTALLDIR}}/VC/Tools/MSVC/14.33.31629/bin/HostX64/x86/link.exe
WIN32_REDIST_DIR=C:/{{VCINSTALLDIR}}/VC/redist/MSVC/14.32.31326/$BUILD_ARCH/Microsoft.VC143.CRT
WIN_UCRT_REDIST_DIR="C:/Program Files (x86)/Windows Kits/10/Redist/10.0.22621.0/ucrt/DLLs/$BUILD_ARCH"

Note the REDIST_DIR entries are replaced with specific version paths for 32-bit compatible components you were asked to install.
At the moment, 32-bit builds have to use a frozen toolchain (compiler 14.32 and SDK 22621) to not cause problems on Windows 7 on old hardware.

Build

Go to C:\mozilla-build (or wherever you extracted the Mozilla build tools) and run
```
start-shell.bat
```
- This will open a UNIX-like shell with the compile environment set up for Visual Studio 2015.
In the shell, cd to your Pale Moon source directory, e.g.
```
cd /c/palemoon-source
```
Start the build:
```
./mach build
```

Be patient. Building will take a bit of time on most systems. Your PC 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.

Important note: before you start building, make sure to exclude the source and target folders from antivirus software or it will severely slow down the build process or may even break it entirely (due to file locks). Either completely disable real-time/on-access scanning before building, or make specific exclusions for your working folders.

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 .zip file in your object folder under the Pale Moon source folder. e.g. for x86:

C:\palemoon-source\obj-i686-pc-mingw32\dist\palemoon-{version}.win32.7z

Generating the installer

If you want to build a self-extracting installer, similar to the off-line installers offered in official builds, you will have to do give the following command:

./mach installer

This will create a self-extracting installer in your object folder under the Pale Moon source folder. e.g. for x86:

C:\palemoon-source\obj-i686-pc-mingw32\dist\palemoon-{version}.win32.installer.exe