Skip to main content

Building the Client

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.

Checking out the source code

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

Building

Conda​

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

Building for each platform​

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.

Build targets​

  • The default target builds the mozillavpn client
  • build_tests builds the unit tests
  • pkg to build the installer package on macOS

Build configure flags​

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)

Useful scripts

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

Troubleshooting

git clean if you're having build troubles​

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.

did you activate your conda environment​

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.

ask for help​

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

Last updated on