SERVER-54872 Create build system document outlines

These will be the site of future build system documentation. We will be
adding to it over time.

2 files changed, 199 insertions, 0 deletions

diff --git a/docs/build_system.md b/docs/build_system.md
new file mode 100644
index 00000000000..d3d1c384591
--- /dev/null
+++ b/docs/build_system.md
@@ -0,0 +1,153 @@
+# The MongoDB Build System
+
+## Introduction
+### System requirements and supported platforms
+
+## How to get Help
+### Where to go
+### What to bring when you go there (SCons version, server version, SCons command line, versions of relevant tools, `config.log`, etc.)
+
+## Known Issues
+### Commonly-encountered issues
+#### `--disable-warnings-as-errors`
+### Reference to known issues in the ticket system
+### How to report a problem
+#### For employees
+#### For non-employees
+
+## Set up the build environment
+### Set up the virtualenv
+### The Enterprise Module
+#### Getting the module source
+#### Enabling the module
+
+## Building the software
+### Commonly-used build targets
+### Building a standard “debug” build
+#### `--dbg`
+### What goes where?
+#### `$BUILD_ROOT/scons` and its contents
+#### `$BUILD_ROOT/$VARIANT_DIR` and its contents
+#### `$BUILD_ROOT/install` and its contents
+#### `DESTDIR` and `PREFIX`
+#### `--build-dir`
+### Running core tests to verify the build
+### Building a standard “release” build
+#### `--separate-debug`
+### Installing from the build directory
+#### `--install-action`
+### Creating a release archive
+
+## Advanced Builds
+### Compiler and linker options
+#### `CC, CXX, CCFLAGS, CFLAGS, CXXFLAGS`
+#### `CPPDEFINES and CPPPATH`
+#### `LINKFLAGS`
+#### `MSVC_VERSION`
+#### `VERBOSE`
+### Advanced build options
+#### `-j`
+#### `--separate-debug`
+#### `--link-model`
+#### `--allocator`
+#### `--cxx-std`
+#### `--linker`
+#### `--variables-files`
+### Cross compiling
+#### `HOST_ARCH` and `TARGET_ARCH`
+### Using Ninja
+#### `--ninja`
+### Cached builds
+#### Using the SCons build cache
+##### `--cache`
+##### `--cache-dir`
+#### Using `ccache`
+##### `CCACHE`
+### Using Icecream
+#### `ICECC`, `ICECRUN`, `ICECC_CREATE_ENV`
+#### `ICECC_VERSION` and `ICECC_VERSION_ARCH`
+#### `ICECC_DEBUG`
+
+## Developer builds
+### Developer build options
+#### `MONGO_{VERSION,GIT_HASH}`
+#### Using sanitizers
+##### `--sanitize`
+##### `*SAN_OPTIONS`
+#### `--dbg` `--opt`
+#### `--build-tools=[stable|next]`
+### Setting up your development environment
+#### `mongo_custom_variables.py`
+##### Guidance on what to put in your custom variables
+##### How to suppress use of your custom variables
+##### Useful variables files (e.g. `mongodbtoolchain`)
+#### Using the Mongo toolchain
+##### Why do we have our own toolchain?
+##### When is it appropriate to use the MongoDB toolchain?
+##### How do I obtain the toolchain?
+##### How do I upgrade the toolchain?
+##### How do I tell the build system to use it?
+### Creating and using build variants
+#### Using `--build-dir` to separate variant build artifacts
+#### `BUILD_ROOT` and `BUILD_DIR`
+#### `VARIANT_DIR`
+#### `NINJA_PREFIX` and `NINJA_SUFFIX`
+### Building older versions
+#### Using` git-worktree`
+### Speeding up incremental builds
+#### Selecting minimal build targets
+#### Compiler arguments
+##### `-gsplit-dwarf` and `/DEBUG:FASTLINK`
+#### Don’t reinstall what you don’t have to (*NIX only)
+##### `--install-action=hardlink`
+#### Speeding up SCons dependency evaluation
+##### `--implicit-cache`
+##### `--build-fast-and-loose`
+#### Using Ninja responsibly
+#### What about `ccache`?
+
+## Making source changes
+### Adding a new dependency
+### Linting and Lint Targets
+#### What lint targets are available?
+#### Using `clang-format`
+### Testing your changes
+#### How are test test suites defined?
+#### Running test suites
+#### Adding tests to a suite
+#### Running individual tests
+
+## Modifying the buid system
+### What is SCons?
+#### `SConstruct` and `SConscripts`
+#### `Environments `and their `Clone`s
+##### Overriding and altering variables
+#### `Targets` and `Sources`
+#### `Nodes`
+##### `File` Nodes
+##### `Program` and `Library` Nodes
+#### `Aliases`, `Depends` and `Requires`
+#### `Builders`
+#### `Emitters`
+#### `Scanners`
+#### `Actions`
+#### `Configure` objects
+#### DAG walk
+#### Reference to SCons documentation
+### Modules
+#### How modules work
+#### The Enterprise module
+##### The `build.py` file
+#### Adding a new module
+### `LIBDEPS` and the `LIBDEPS` Linter
+#### Why `LIBDEPS`?
+#### `LIBDEPS` vs `LIBDEPS_PRIVATE vs LIBDEPS_INTERFACE`
+#### Reverse edges with `DEPS_DEPENDENTS`
+#### The `LIBDEPS` lint rules and tags
+#### `LIBDEPS_TAGS`
+##### `init-no-global-side-effects`
+#### Using the LIBDEPS Linter
+### Debugging build system failures
+#### Using` -k` and `-n`
+#### `--debug=[explain, time, stacktrace]`
+#### `--libdeps-debug`
diff --git a/docs/build_system_reference.md b/docs/build_system_reference.md
new file mode 100644
index 00000000000..65cfea7bfea
--- /dev/null
+++ b/docs/build_system_reference.md
@@ -0,0 +1,46 @@
+# MongoDB Build System Reference
+
+## MongoDB Build System Requirements
+### Recommended minimum requirements
+### Python modules
+### External libraries
+### Enterprise module requirements
+### Testing requirements
+
+## MongoDB customizations
+### SCons modules
+### Development tools
+#### Compilation database generator
+### Build tools
+#### IDL Compiler
+### Auxiliary tools
+#### Ninja generator
+#### Icecream tool
+#### ccache tool
+### LIBDEPS
+#### Design
+#### Linting and linter tags
+
+## Build system configuration
+### SCons configuration
+#### Frequently used flags and variables
+### MongoDB build configuration
+#### Frequently used flags and variables
+### Targets and Aliases
+
+## Build artifacts and installation
+### Hygienic builds
+### AutoInstall
+### AutoArchive
+
+## MongoDB SCons style guide
+### Sconscript Formatting Guidelines
+#### Vertical list style
+#### Alphabetize everything
+### `Environment` Isolation
+### Declaring Targets (`Program`, `Library`, and `CppUnitTest`)
+### Invoking external tools correctly with `Command`s
+### Customizing an `Environment` for a target
+### Invoking subordinate `SConscript`s
+#### `Import`s and `Export`s
+### A Model `SConscript` with Comments