1*ef3a692cSMatthias Maennich# [Bazel Platforms](https://bazel.build) 2*ef3a692cSMatthias Maennich 3*ef3a692cSMatthias MaennichThis repository houses all canonical 4*ef3a692cSMatthias Maennich[constraint_setting()](https://bazel.build/reference/be/platforms-and-toolchains#constraint_setting)s, 5*ef3a692cSMatthias Maennich[constraint_value()](https://bazel.build/reference/be/platforms-and-toolchains#constraint_value)s 6*ef3a692cSMatthias Maennichand 7*ef3a692cSMatthias Maennich[platform()](https://bazel.build/reference/be/platforms-and-toolchains#platform)s 8*ef3a692cSMatthias Maennichthat are universally useful across languages and Bazel projects. 9*ef3a692cSMatthias Maennich 10*ef3a692cSMatthias MaennichFor questions or concerns please email 11*ef3a692cSMatthias Maennich[[email protected]](mailto://[email protected]). 12*ef3a692cSMatthias Maennich 13*ef3a692cSMatthias Maennich# Motivation 14*ef3a692cSMatthias Maennich 15*ef3a692cSMatthias MaennichConstraints must be carefully organized to avoid fragmentation. If two different 16*ef3a692cSMatthias Maennichdeclarations for, say, cpu=x86_64 were to exist at the same time then select() 17*ef3a692cSMatthias Maennichstatements and toolchain selection would stop working across languages and 18*ef3a692cSMatthias Maennichprojects. 19*ef3a692cSMatthias Maennich 20*ef3a692cSMatthias Maennich# Process 21*ef3a692cSMatthias Maennich 22*ef3a692cSMatthias MaennichThis repository only includes truly ubiquitous constraints. 23*ef3a692cSMatthias Maennich 24*ef3a692cSMatthias MaennichMost common constraints -- that is settings and values that can be used across 25*ef3a692cSMatthias Maennichprojects - fall into specific areas like "Apple" or "Java". These are declared 26*ef3a692cSMatthias Maennichin those areas' respective repositories. 27*ef3a692cSMatthias Maennich 28*ef3a692cSMatthias MaennichA very few constraints (such as OS and cpu) are relevant for essentially all 29*ef3a692cSMatthias Maennichprojects across all areas. These are what this repository is for. 30*ef3a692cSMatthias Maennich 31*ef3a692cSMatthias Maennich# Adding a canonical constraint value 32*ef3a692cSMatthias Maennich 33*ef3a692cSMatthias MaennichTo add a new canonical constraint value, prepare a PR adding it to that the 34*ef3a692cSMatthias Maennichappropriate BUILD file. 35*ef3a692cSMatthias Maennich 36*ef3a692cSMatthias MaennichNote that even global constraint values are typically area values. For example, 37*ef3a692cSMatthias Maennichios is an area value for the global setting os but belongs in the apple area. 38*ef3a692cSMatthias MaennichFor the PR's reviewer(s) choose an owner of this repository plus an owner of the 39*ef3a692cSMatthias Maennicharea repository this references.. 40*ef3a692cSMatthias Maennich 41*ef3a692cSMatthias MaennichA constraint value should be: 42*ef3a692cSMatthias Maennich 43*ef3a692cSMatthias Maennich- semantically clear, particularly in its distinctions from other values of 44*ef3a692cSMatthias Maennich the same setting 45*ef3a692cSMatthias Maennich 46*ef3a692cSMatthias Maennich- well-named: consistent with existing values of the same setting and easy to 47*ef3a692cSMatthias Maennich understand at usage sites 48*ef3a692cSMatthias Maennich 49*ef3a692cSMatthias Maennich- well-documented 50*ef3a692cSMatthias Maennich 51*ef3a692cSMatthias MaennichRemember that this value will apply for the entire Bazel community and its 52*ef3a692cSMatthias Maennichsemantics will be difficult to impossible to change once it starts being used. 53*ef3a692cSMatthias Maennich 54*ef3a692cSMatthias Maennich# Adding a canonical constraint setting 55*ef3a692cSMatthias Maennich 56*ef3a692cSMatthias MaennichNew canonical constraint settings should be rare and well-justified. 57*ef3a692cSMatthias Maennich 58*ef3a692cSMatthias MaennichTo add a new setting, prepare a design document according to Bazel's design 59*ef3a692cSMatthias Maennichreview process. This document should explain the need for a new setting and why 60*ef3a692cSMatthias Maennichit belongs here vs. area-specific repositories. It should clearly explain 61*ef3a692cSMatthias Maennichsemantics, initial values, and criteria for adding new values. 62*ef3a692cSMatthias Maennich 63*ef3a692cSMatthias MaennichOnce the design is approved prepare a PR for the actual change. If any values 64*ef3a692cSMatthias Maennichare area-specific, include the area repositories' owners as reviewers. 65*ef3a692cSMatthias Maennich 66*ef3a692cSMatthias Maennich# Private changes to global constraints 67*ef3a692cSMatthias Maennich 68*ef3a692cSMatthias MaennichIf you'd like to experiment with changes to global settings or values, you can 69*ef3a692cSMatthias Maennichfork this repo for experimental purposes. But in the interest of community 70*ef3a692cSMatthias Maennichhealth and interoperability please don't share your changes with anyone not 71*ef3a692cSMatthias Maennichinvolved with the experiment. For wider distribution, submit a proper change 72*ef3a692cSMatthias Maennichhere. 73*ef3a692cSMatthias Maennich 74*ef3a692cSMatthias MaennichNote that you can declare constraint_values in your own repo that are members of 75*ef3a692cSMatthias Maennichthe global constraint_settings. This lets you "extend" global settings within 76*ef3a692cSMatthias Maennichthe confines of your own project. But don't do this if you expect other projects 77*ef3a692cSMatthias Maennichto use these changes - this can easily lead to fragmentation conflicts. 78*ef3a692cSMatthias Maennich 79*ef3a692cSMatthias MaennichIf you need custom constaint_settings, just declare them in your own repo. They 80*ef3a692cSMatthias Maennichare, by definition, not global. 81*ef3a692cSMatthias Maennich 82*ef3a692cSMatthias MaennichIf you really need a permanent global change and it isn't design-approved for 83*ef3a692cSMatthias Maennichthis repo, start a thread on 84*ef3a692cSMatthias Maennich[GitHub](https://github.com/bazelbuild/bazel/discussions) to discuss options. 85