Build instructions for Windows

Talk about code development, features, specific bugzilla bugs, enhancements, patches, and other highly technical things.
Forum rules
Please keep everything here strictly on-topic.
This board is meant for Pale Moon source code development related subjects only like code snippets, patches, specific referenced Bugzilla bugs, mercurial, etc.

This is not for tech support! Please do not post tech support questions in the "Development" board!
Please make sure not to use this board for support questions. Most "bug reports" do not belong in this board and should initially be posted in Community Support or other relevant support boards.

Please keep things on-topic as this forum will be used for reference for Pale Moon development. Expect topics that aren't relevant as such to be moved or deleted.
User avatar
Pale Moon guru
Pale Moon guru
Posts: 27813
Joined: 2011-08-28, 17:27
Location: Tranås, SE

Build instructions for Windows

Post by Moonchild » 2018-07-18, 22:30

These instructions are for building Pale Moon 28.* (using UXP)

  • Microsoft Visual Studio 2015 (Community Edition (free) or Pro/Paid version -- Express won't work)
    We will assume here you are using the Community Edition.
  • MozillaBuild 2.x, e.g. 2.2
  • At least 4 GB Ram (8 GB or more recommended)
  • Plenty of free disk space
  • At least Windows 7 64-bit
Prerequisite caveats
  • To get Visual Studio 2015 CE you need a Developer Account (simply a Microsoft account). Microsoft will try to push VS 2017 on you but that will not work. You must get 2015 from the "previous versions" part of the site.
  • Launch VS2015 after installation to initialize the environment, start the IDE and get the latest updates. Launch after updating to finish up the update, after which you can close the IDE. For x64 builds, make sure you install the x64 build tools
    (Note: You will be asked to register with Microsoft when launching it the first time; simply log in with your developer account in the IDE and you're set.)
  • Make sure you install the correct components for "C++ development"; other languages are not necessary and not installing them will save you (heaps of) disk space.
Getting the Source

Download the source from or clone the UXP repo with git.
Make sure you unpack/clone to a path that does not contain spaces, e.g. c:\palemoon-source to prevent build system issues.

If you cloned the git repo be sure to switch to the desired release branch. Since the UXP platform repo contains multiple applications and trunk may be unstable, this is important.

This source tree will contain everything needed for both x86 and x64 builds of Pale Moon (they share the same release source code).

Build Instructions


Create a file called .mozconfig in the source folder you unpacked the source in.
(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 of any name in your home folder or a folder of your choice, and use

Code: Select all

export MOZCONFIG=path/to/your/mozconfig.txt
in your command prompt before starting a build. If the file is in your home folder, you can simply use ~/mozconfig.txt (~ is your home folder).
Note: the command prompt when building is a unix-like environment which uses forward slashes for paths.

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

For x86 (32-bit):

Code: Select all

ac_add_options --enable-application=palemoon
ac_add_options --enable-optimize="-O2"
ac_add_options --enable-jemalloc
ac_add_options --disable-eme
ac_add_options --disable-webrtc
ac_add_options --enable-devtools
ac_add_options --disable-gamepad
ac_add_options --disable-parental-controls

WIN_UCRT_REDIST_DIR="C:/Program Files (x86)/Windows Kits/10/Redist/ucrt/DLLs/x86"
For x64 (64-bit):

Code: Select all

ac_add_options --enable-application=palemoon
ac_add_options --enable-optimize="-O2"
ac_add_options --enable-jemalloc
ac_add_options --disable-eme
ac_add_options --disable-webrtc
ac_add_options --enable-devtools
ac_add_options --disable-gamepad
ac_add_options --disable-parental-controls 

WIN_UCRT_REDIST_DIR="C:/Program Files (x86)/Windows Kits/10/Redist/ucrt/DLLs/x64"
To speed up the build you probably want to exclude building automated tests (which aren't actively used and may not always build properly)

Code: Select all

ac_add_options --disable-tests
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.

  • Go to C:\mozilla-build (or wherever you extracted to mozilla build tools) and run start-shell-msvc2015.bat
    This will open a UNIX-like shell with the compile environment set up for Visual Studio 2015 with a 32-bit target. Please do not use the -x64 batch file just because you are on a 64-bit O.S. when building x86.
    The -x64 batch file is for launching a 64-bit build environment and building a 64-bit browser. So for creating an x64 build of Pale Moon, run start-shell-msvc2015-x64.bat
  • In the shell, cd to your pale moon source directory, e.g.

    Code: Select all

    cd /c/palemoon-source
    if you installed the source in C:\palemoon-source
  • Start the build:

    Code: Select all

    ./mach build
  • Be patient. Building will take a while. 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 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.


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 binaries to integrate additional code, pack up the omnijar files, and have a ready-to-use browser. You do this by running

Code: Select all

./mach package
This will create a properly packaged .zip file in your object folder under the Pale Moon source folder. e.g.:
C:\palemoon-source\obj-i686-pc-mingw32\dist\palemoon-{version} (for x86)

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:

Code: Select all

./mach installer
This will create a self-extracting installer in your object folder under the Pale Moon source folder. e.g.:
C:\palemoon-source\obj-i686-pc-mingw32\dist\install\sea\palemoon-{version}.en-US.win32.installer.exe (for x86)
Last edited by Moonchild on 2018-07-18, 22:31, edited 1 time in total.
"There will be times when the position you advocate, no matter how well framed and supported, will not be accepted by the public simply because you are who you are." -- Merrill Rose