Build MongoDB From Source

As you make changes, you will need to build the server and tools and run the appropriate test suites. Though the exact dependencies and semantics differ by operating system, building the server from source has the same basic steps.

Dependencies & Installation

MongoDB uses SCons to build the Server and associated tools. While it is unnecessary to know all the intricacies of SCons, glancing over the documentation may be helpful. SCons is unlikely to come preinstalled on your system, so make sure to install it using your preferred package manager.

Other basic requirements, independent of system, are to install Git and a recent 2.7.x version of Python. Further requirements are system-dependent and for both SCons and running the tests:

  • On Linux, you will need to install a compiler gcc or clang, as well as Libc headers which are usually included in a package named glibc-devel.
  • On Mac OS X, you will need to install XCode, specifically the command line tools.
  • On Windows, you will need to install Visual Studio 2010 or later.
  • On FreeBSD, the included compiler (gcc or clang) should suffice, but you will need to install devel\libexecinfo.

Depending on your needs and the parts of the database you are working on, you may also need to install to install OpenSSL.

Building With SCons

Building the server executables consists of passing SCons a target, for example when we build the MongoDB database server executable:

scons mongod

If you’re on Windows, this will instead be scons mongod.exe.

Other executables you may need to build include mongos or mongo, depending on what you are working on. You can pass SCons multiple targets in a list if necessary:

scons mongod mongo mongos

Alternatively, you may build everything, which includes mongo, mongod, mongos, the tools, and all the C++ unit tests:

scons all

All of these commands should be run from the root of the MongoDB repository.

While certain top level build artifacts (like mongod and mongos) get copied to the top of the source tree during a build, other files like the C++ unit tests are generated underneath a directory called build. The build directory is created is created at the top level of the source tree as soon as you build anything.

Building can take a while, depending on which target(s) you are building and the capabilities of your computer. Without getting into all the intricacies of SCons, here are some flags to get you started:

  • --help

    This options provides help on both the intrinsic and local options. Read this.

  • -j <N>

    This option controls the number of parallel jobs SCons will use. Depending on what the local hardware is, you probably want to set this from anything between 0 and 32. Keep in mind that this isn’t just compilation, but also linking. Having 32 concurrent linking jobs running can make your machine pretty sluggish. Find a number that works for you. When running on Windows machines, it is recommended to install pywin32 or ActivePython if you wish to do parallel builds.

  • --ssl

    This option builds MongoDB with SSL support.

The following table lists some SCons aliases that are helpful with testing:

Alias Effect
all Builds everything (core, tools, and all tests)
tools Builds the server tools (mongodump, mongostat, etc.)
test Builds the dbtest program.
lint Runs the code linter (cool!) – do this!
msi Builds the Windows MSI installer.
core Builds mongod, mongos, and the mongo shell.
install Installs to the directory used with the --prefix option, or to /usr/local if no --prefix was specified.
smoke Runs the “dbtest” test.
smokeCppUnitTests Runs the C++ unit tests.
smokeJsCore Runs (some of!) the Javascript integration tests.

Other aliases related to testing exist. Our aliases fall into two categories: ones that simply build targets, and ones that build targets and then run programs, typically a test harness of some kind. These latter aliases have dependencies defined for them, such that all the build targets that are necessary for a certain test are up to date before running the test. The only difference between, for example, the ‘test’ and the ‘smoke’ aliases is that the former builds all the dependencies for the program named dbtest, and the latter does all that same work and additionally runs the dbtest program.