/** @page building Building & Installation
@brief Instructions for building and installing the slang library and tools

@tableofcontents

@section source Getting the Source

All source code is hosted on [GitHub](https://github.com/MikePopoloski/slang)

@code{.ansi}
git clone https://github.com/MikePopoloski/slang.git
@endcode

git submodules are used for some dependencies, so they need to be pulled as well:

@code{.ansi}
git submodule update --init --recursive
@endcode

@section dependencies Dependencies

slang requires the following dependencies in order to build:
- [python 3](https://www.python.org/)
- [CMake](https://cmake.org/) (3.15 or later)
- C++17 compatible compiler

@section building-start Quick Start

Instructions on quickly getting a build going for common platforms.

## Linux

On many common systems, a modern C++ compiler is not configured as the default.
This assumes you've installed [GCC 9](https://gcc.gnu.org/gcc-9/) and that it's
available on your path, and that you want a release build that will be installed
to `/usr/local/bin`.

@code{.ansi}
mkdir build && cd build
cmake -DCMAKE_CXX_COMPILER=g++-9 -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local/bin ..
make -j8
@endcode

Tests are built by default. You can run them via ctest:

@code{.ansi}
ctest
@endcode

Or run the unit tests directly:

@code{.ansi}
bin/unittests
@endcode

Installation:

@code{.ansi}
make install
@endcode

## Windows

VisualStudio 2019 has built-in support for cmake; simply open the slang root folder
and press build.

@section build-options Build Options

Besides the built-in cmake options, there are slang-specific options that may be
set to customize the build:
Option | Description | Default
------ | ----------- | -------
SLANG_INCLUDE_TESTS | Include tests in the build | ON
SLANG_INCLUDE_DOCS | Include docs in the build | OFF
SLANG_INCLUDE_LLVM | Include LLVM in the build for generating simulation binaries | OFF
BUILD_SHARED_LIBS | Build a shared library instead of static | OFF
SLANG_COVERAGE | Enable Clang code coverage | OFF
SLANG_SANITIZERS | A list of Clang sanitizers to include in the build | ""
FUZZ_TARGET | Turn on to enable some changes to make binaries easier to fuzz test | OFF
CI_BUILD | Enable additional longer-running tests for automated builds | OFF
DOXYGENPY_PATH | When building docs, the path to the doxygen.py tool | ""
SLANG_USE_SYSTEM_LIBS | Configures the build to use dependencies already installed on the system (such as fmt and xxhash) instead of the ones included in the repo | OFF

@section build-scripts Build Scripts

This section documents scripts that are invoked during the build that may be of
general interest or useful to know if you're modifying how the build works.

## Version info

On every build, the current git revision hash is queried and included in the `Version.cpp`
header to expose to the rest of the library. If the revision is unchanged from the last
build no additional work will be done.

## Syntax generation

Syntax nodes in slang are expressed in the `scripts/syntax.txt` file and processed
during the build into generated C++ classes by the `syntax_gen.py` script.

## Diagnostic generation

Diagnostics, similarly to syntax nodes, are expressed in the `scripts/diagnostics.txt`
file and processed into C++ definitions by the `diagnostic_gen.py` script.

@section doc-builds Building Documentation

This section contains instructions for building the documentation.

## Dependencies

- [doxygen](http://www.doxygen.nl/) - at least 1.8.17
- [doc build environment](https://github.com/MikePopoloski/m.css)

## Steps

Run cmake with docs enabled and the path to the `doxygen.py` script in the `m.css` checkout:

@code{.ansi}
cmake -DSLANG_INCLUDE_DOCS=ON -DDOXYGENPY_PATH=/path/to/m.css/documentation/doxygen.py
@endcode

Run the build:

@code{.ansi}
make docs
@endcode

The output website is located at `docs/html/`

*/
