1*eed53cd4SHONG Yifan# Writing a custom C++ toolchain 2*eed53cd4SHONG Yifan 3*eed53cd4SHONG YifanThis example shows how to define and use a simple custom C++ toolchain. 4*eed53cd4SHONG Yifan 5*eed53cd4SHONG YifanOutput is non-functional: simple scripts replace compilation and linking 6*eed53cd4SHONG Yifanwith `I compiled!` and `I linked!` messages. 7*eed53cd4SHONG Yifan 8*eed53cd4SHONG Yifan[BUILD](BUILD) provides detailed implementation walkthrough. The fundamental 9*eed53cd4SHONG Yifansequence is: 10*eed53cd4SHONG Yifan 11*eed53cd4SHONG Yifan1. Define the toolchain 12*eed53cd4SHONG Yifan1. Define how to invoke the toolchain. 13*eed53cd4SHONG Yifan 14*eed53cd4SHONG Yifan`1` is C++-specific: the logic and structure depends specifically on C++'s 15*eed53cd4SHONG Yifanlanguage model. Other languages have their own models. 16*eed53cd4SHONG Yifan 17*eed53cd4SHONG Yifan`2` supports two variations. `--crosstool_top` / `--cpu`, the legacy version, 18*eed53cd4SHONG Yifanis C++-specific. `--platforms`, the modern version, is much more generic and 19*eed53cd4SHONG Yifansupports all languages and features like [incompatible target 20*eed53cd4SHONG Yifanskipping](https://docs.bazel.build/versions/master/platforms.html#skipping-incompatible-targets). See 21*eed53cd4SHONG Yifan[Building with 22*eed53cd4SHONG YifanPlatforms](https://docs.bazel.build/versions/master/platforms-intro.html) and 23*eed53cd4SHONG Yifanits [C++ 24*eed53cd4SHONG Yifannotes](https://docs.bazel.build/versions/master/platforms-intro.html#c) for 25*eed53cd4SHONG Yifanfull review. 26*eed53cd4SHONG Yifan 27*eed53cd4SHONG Yifan## Building with the default toolchain 28*eed53cd4SHONG Yifan 29*eed53cd4SHONG Yifan``` 30*eed53cd4SHONG Yifan$ bazel clean 31*eed53cd4SHONG Yifan$ bazel build //examples/custom_toolchain:buildme 32*eed53cd4SHONG Yifan$ file bazel-bin/examples/custom_toolchain/libbuildme.a 33*eed53cd4SHONG Yifanbazel-bin/examples/custom_toolchain/libbuildme.a: current ar archive 34*eed53cd4SHONG Yifan``` 35*eed53cd4SHONG Yifan 36*eed53cd4SHONG Yifan## Custom toolchain with platforms 37*eed53cd4SHONG Yifan 38*eed53cd4SHONG YifanThis mode requires `--incompatible_enable_cc_toolchain_resolution`. Without this 39*eed53cd4SHONG Yifanflag, `--platforms` and `--extra_toolchains` are ignored and the default 40*eed53cd4SHONG Yifantoolchain triggers. 41*eed53cd4SHONG Yifan 42*eed53cd4SHONG Yifan``` 43*eed53cd4SHONG Yifan$ bazel clean 44*eed53cd4SHONG Yifan$ bazel build //examples/custom_toolchain:buildme --platforms=//examples/custom_toolchain:x86_platform --extra_toolchains=//examples/custom_toolchain:platform_based_toolchain --incompatible_enable_cc_toolchain_resolution 45*eed53cd4SHONG YifanDEBUG: /usr/local/google/home/gregce/bazel/rules_cc/examples/custom_toolchain/toolchain_config.bzl:17:10: Invoking my custom toolchain! 46*eed53cd4SHONG YifanINFO: From Compiling examples/custom_toolchain/buildme.cc: 47*eed53cd4SHONG Yifanexamples/custom_toolchain/sample_compiler: running sample cc_library compiler (produces .o output). 48*eed53cd4SHONG YifanINFO: From Linking examples/custom_toolchain/libbuildme.a: 49*eed53cd4SHONG Yifanexamples/custom_toolchain/sample_linker: running sample cc_library linker (produces .a output). 50*eed53cd4SHONG Yifan 51*eed53cd4SHONG Yifan$ cat bazel-bin/examples/custom_toolchain/libbuildme.a 52*eed53cd4SHONG Yifanexamples/custom_toolchain/sample_linker: sample output 53*eed53cd4SHONG Yifan``` 54*eed53cd4SHONG Yifan 55*eed53cd4SHONG YifanThis example uses a long command line for demonstration purposes. A real project 56*eed53cd4SHONG Yifanwould [register toolchains](https://docs.bazel.build/versions/master/toolchains.html#registering-and-building-with-toolchains) 57*eed53cd4SHONG Yifanin `WORKSPACE` and auto-set 58*eed53cd4SHONG Yifan`--incompatible_enable_cc_toolchain_resolution`. That reduces the command to: 59*eed53cd4SHONG Yifan 60*eed53cd4SHONG Yifan``` 61*eed53cd4SHONG Yifan$ bazel build //examples/custom_toolchain:buildme --platforms=//examples/custom_toolchain:x86_platform 62*eed53cd4SHONG Yifan``` 63*eed53cd4SHONG Yifan 64*eed53cd4SHONG Yifan## Custom toolchain with legacy selection: 65*eed53cd4SHONG Yifan 66*eed53cd4SHONG Yifan``` 67*eed53cd4SHONG Yifan$ bazel clean 68*eed53cd4SHONG Yifan$ bazel build //examples/custom_toolchain:buildme --crosstool_top=//examples/custom_toolchain:legacy_selector --cpu=x86 69*eed53cd4SHONG YifanDEBUG: /usr/local/google/home/gregce/bazel/rules_cc/examples/custom_toolchain/toolchain_config.bzl:17:10: Invoking my custom toolchain! 70*eed53cd4SHONG YifanINFO: From Compiling examples/custom_toolchain/buildme.cc: 71*eed53cd4SHONG Yifanexamples/custom_toolchain/sample_compiler: running sample cc_library compiler (produces .o output). 72*eed53cd4SHONG YifanINFO: From Linking examples/custom_toolchain/libbuildme.a: 73*eed53cd4SHONG Yifanexamples/custom_toolchain/sample_linker: running sample cc_library linker (produces .a output). 74*eed53cd4SHONG Yifan 75*eed53cd4SHONG Yifan$ cat bazel-bin/examples/custom_toolchain/libbuildme.a 76*eed53cd4SHONG Yifanexamples/custom_toolchain/sample_linker: sample output 77*eed53cd4SHONG Yifan``` 78*eed53cd4SHONG Yifan 79