Building & Installation

Instructions for building and installing the slang library and tools.

Getting the Source

All source code is hosted on GitHub

git clone https://github.com/MikePopoloski/slang.git

Dependencies

slang requires the following dependencies in order to build:

  • python 3
  • CMake (3.15 or later)
  • C++17 compatible compiler
    • GCC 9.1 is the minimum supported version
    • clang 10 is the minimum supported version
    • MSVC support is tested only against the most recent update of VS 2022
    • Other compilers (including earlier versions of the ones listed above) may or may not work. Note that AppleClang has its own versioning scheme – you generally need a newer AppleClang to get full C++17 support, and Apple ties Xcode updates to OS versions so you may be forced to update your OS.

Quick Start

The build should work out of the box on all supported platforms with the same set of steps:

cmake -B build
cmake --build build

Tests are included in the configuration by default. You can run them via ctest:

cd build && ctest --output-on-failure

Build Options

Besides the built-in CMake options, there are slang-specific options that may be set to customize the build:

OptionDescriptionDefault
SLANG_INCLUDE_TOOLSInclude tools targets in the build (such as the slang driver executable)ON
SLANG_INCLUDE_TESTSInclude tests in the buildON
SLANG_INCLUDE_INSTALLInclude installation targets in the buildON
SLANG_INCLUDE_DOCSInclude docs in the buildOFF
SLANG_INCLUDE_PYLIBInclude Python bindings in the buildOFF
SLANG_INCLUDE_COVERAGEInclude code coverage targets in the buildOFF
BUILD_SHARED_LIBSBuild a shared library instead of staticOFF
SLANG_FUZZ_TARGETTurn on to enable some changes to make binaries easier to fuzz testOFF
SLANG_CI_BUILDEnable additional longer-running tests for automated buildsOFF
SLANG_CLANG_TIDYThe path to a clang-tidy binary to run against the slang sources""
SLANG_WARN_FLAGSExtra compiler warning flags to enable when building slang""
SLANG_CMAKECONFIG_INSTALL_DIRIf install rules are included, this path is used to install the generated CMake config for the slang package${CMAKE_INSTALL_LIBDIR}/cmake/slang

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.

Building Documentation

This section contains instructions for building the documentation.

Dependencies

Steps

Run CMake with docs enabled:

cmake -B build -DSLANG_INCLUDE_DOCS=ON
cmake --build build --target docs

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

Installation

CMake can be used to install slang.

cmake --install build --strip

You can use the --prefix option to control where the installation gets placed in case you want something other than the default on your system.

Integration

Integrating the slang library into your own build is straightforward if you use CMake. Link your target to the slang::slang CMake target and everything else should be set up for you automatically.

Some possible options for locating the slang package are as follows:

External Package

If you followed the installation steps above and installed the slang package on your system in one of the default locations, you should be able to use a simple find_package to pull it into your build.

cmake_minimum_required(VERSION 3.15)
project(example)

find_package(slang 1.0.0)

add_executable(example example.cpp)
target_link_libraries(example PRIVATE slang::slang)

See this GitHub project as an example of integrating slang using this method.

FetchContent

Instead of installing the slang package on your system, you can instead instruct CMake to pull the source from GitHub and build it as part of your own project.

cmake_minimum_required(VERSION 3.15)
project(example)

# Note: this example just pulls the head master branch
# for slang, but a real project would very likely pin
# this to a specific tag and only update when ready
# to accept a new version.
include(FetchContent)
FetchContent_Declare(
  slang
  GIT_REPOSITORY https://github.com/MikePopoloski/slang.git
  GIT_SHALLOW ON)
FetchContent_MakeAvailable(slang)

add_executable(example example.cpp)
target_link_libraries(example PRIVATE slang::slang)

See this GitHub project as an example of integrating slang using this method.