Building the for the first time can be a bit daunting.

We strongly recommend first building for the platform you are on. For example if you're on a windows machine, make a windows build; a mac, make a mac build etc.

When building for android and iOS you will be cross-compiling (building for a different platform than the machine you're on) which can make things a little trickier.

To try and provide a smooth dev experience we focus on ensuring that a minimal set of workflows are always working. There's nothing stopping you from using your preferred tools and workflows, but you are in the wild.

git clone https://github.com/mozilla-mobile/mozilla-vpn-client.git
cd mozilla-vpn-client
git submodule update --init --recursive

Wherever possible, dependencies are managed using conda. Please install miniconda.

Then run:

• conda env create -f env.yml
• conda activate vpn

For windows, see windows docs

All other dependency installation is discussed in each platform page:

• Linux
  • Build on Linux
  • Develop in VS Code
• Windows
  • Build on Windows
  • Develop in Visual Studio
• Mac
  • Build on Mac
  • Develop in VS Code or Xcode
• Android
  • Build on Linux, Mac, or Windows
  • Develop in VS Code
• iOS
  • Build on Mac
  • Develop in VS Code or Xcode
  • Xcode required to build
• wasm

Before submitting a Pull Request, please, install the clang format pre-commit hook: ./scripts/git-pre-commit-format install. See here for more details.

• The default target builds the mozillavpn client
• build_tests builds the unit tests
• dummyvpn is needed for the functional tests
• pkg to build the installer package on macOS

The following are cmake flags that you may need to use. cmake flags are passed to the command line argument with -D e.g. the flag CMAKE_BUILD_TYPE would be set by adding -DCMAKE_BUILD_TYPE=Release to your cmake command.

cmake flags:

• CMAKE_PREFIX_PATH=<Qt install path>/lib/cmake: can be set if CMake is unable to locate a viable Qt installation in your PATH. (This may be an error message like Unknown CMake command "qt_add_executable”.)
• CMAKE_BUILD_TYPE=Release: can be set to generate a release build, otherwise a Debug build is generated by default.
• CMAKE_INSTALL_PREFIX: the install path prefix e.g. /usr
• CMAKE_OSX_ARCHITECTURES: set to "arm64;x86_64" to build a universal build

other flags:

• BUILD_TESTING=ON: can be set to build, and execute the unit tests using CTest
• BUILD_ID=<string>: sets the build identifier that will be embedded into the project. If left unset, this will generate a timestamp when configuring the Makefiles.
• CODE_SIGN_IDENTITY=<Certificate Identity>: can be set to enable code signing during the build process (MacOS / iOS).
• INSTALLER_SIGN_IDENTITY=<Certificate Identity>: can be set to enable signing of the installer package (MacOS / iOS).
• BUILD_OSX_APP_IDENTIFIER=<App Identifier>: can be set to change the application bundle identifier. This defaults to org.mozilla.macos.FirefoxVPN if not set. (MacOS / iOS)
• BUILD_VPN_DEVELOPMENT_TEAM=<Development Team ID>: can be set to change the development team used for Xcode certificates. This defaults to 43AQ936H96 if not set. (MacOS / iOS)

• ./scripts/utils/bake_shaders.sh: if you want to change the shaders

It's easy for your local build to get messed up. When in doubt do a git clean to blow away all generated files. Running git clean -xfdi . from the root of the folder provides you an interactive space where you can review everything that's going to be deleted. You may want to exclude .vscode or .env that you've set-up just the way you like.

You'll need to run conda activate vpn every time you open a new terminal. If you forget and then run cmake the build can get confused / stuck. git clean, make sure conda environment is activated, try again.

We are on a mission to make building easy. If you've tried the above two steps, don't get stuck ask for help.