Configuration

This document will explain cppship's configuration system. Actually, things are not fully designed, and are mostly copied from Rust Cargo.

Profile

You can use [profile] to configure options for all profile, you can use [profile.debug] or [profile.release] to configure in debug or release mode. [profile] and [profile.debug] will be merged in order.

Options

• cxxflags: a list
• linkflags: a list
• definitions: a list, macro definitions, eg. ["NDEBUG"]
• asan: true or false, enable address sanitizer or not, default is false, cannot be combined with tsan
• tsan: true or false, enable thread sanitizer or not, default is false, cannot be combined with asan or leak
• ubsan: true or false, enable undefined sanitizer or not, default is false
• leak: true or false, enable leak sanitizer or not, default is false, cannot be combined with tsan

Default values

• [profile.debug]
  • cxxflags: ["-g"]
• [profile.release]
  • cxxflags: ["-O3"]
  • definitions: ["NDEBUG"]

Special defaults

• ubsan: if you don't specify it, profile.debug will set it to true. if it is specified in any configuration(including conditional configuration, defaults will not be generated)

Conditional configuration

After making cppship workable in Windows MSVC, I realized that conditional configuration is unavoidable in C++. Now conditional. configuration is accomplished via the following:

# target.<cfg>.profile
[target.'cfg(not(compiler = "msvc"))'.profile]
cxxflags = ["-Wall", "-Wextra", "-Werror", "-Wno-unused-parameter", "-Wno-missing-field-initializers"]

[target.'cfg(compiler = "msvc")'.profile]
cxxflags = ["/Zc:__cplusplus", "/Zc:preprocessor", "/MP"]

cfg grammar

Note: currently nested predicate is not supported.

^Syntax
ConfigurationPredicate :
      ConfigurationOption
   | ConfigurationAll
   | ConfigurationAny
   | ConfigurationNot

ConfigurationOption :
   [IDENTIFIER] (= ([STRING_LITERAL] | [RAW_STRING_LITERAL]))^?

ConfigurationAll
   all ( ConfigurationPredicateList^? )

ConfigurationAny
   any ( ConfigurationPredicateList^? )

ConfigurationNot
   not ( ConfigurationPredicate )

ConfigurationPredicateList
   ConfigurationPredicate (, ConfigurationPredicate)^* ,^?

Configuration options

• os:
  • windows
  • macos
  • linux
• compiler:
  • gcc
  • msvc
  • clang
  • apple_clang