== Command Line Options ==

The behavior of compilers are primarily controlled with [https://en.wikipedia.org/wiki/Command-line_interface#Command-line_option switches]. For example, `-I${prefix}/include` and `-L${prefix}/lib` tell the [https://en.wikipedia.org/wiki/C_(programming_language) C] [https://en.wikipedia.org/wiki/Preprocessor preprocessor] and [https://en.wikipedia.org/wiki/Linker_(computing) linker] to look in the [https://guide.macports.org/chunked/reference.variables.html MacPorts prefix] for header files and libraries respectively. However, changing compiler behavior with switches can cause problems.
* Order matters.
 * `-I${prefix}/include -I${worksrcpath}/include` and `-I${worksrcpath}/include -I${prefix}/include` produce different results if different header files with the same name are in both location.
 * Such errors can be subtle and difficult to track down, especially when the header files are from different versions of the same packages (e.g. during the upgrade process).
 * The  MacPorts construct `conflicts_build` can be used to prevent the conflicting header files from being simultaneously installed, but this not ideal.
 * Using `-isystem` instead of `-I` can more [https://gcc.gnu.org/onlinedocs/gcc/Directory-Options.html precisely control] search order, but this also [https://trac.macports.org/ticket/40656 causes problems]. 
 * The search order for libraries has similar problems, but it is more difficult to precisely control library search order (there is just `-L` or using the full library path name).
 * The MacPorts [https://guide.macports.org/chunked/development.buildbot.html buildbot] is careful to build a port only with the minimal set of dependencies active, which prevents most search order issues.
* Switches  can be “baked in” the installed files.
 * [https://trac.macports.org/ticket/49801 Some packages] record the history of the switches they were built with.
 * Some packages use the same switches they were built with to build other packages.
 * At best, this is unnecessary noise. At worst, it causes build problems that can be difficult to diagnose.
 * The switches `-isysroot` and ` -Wl,-syslibroot` are particularly problematic.
  * Major upgrades of Xcode usually remove old [https://en.wikipedia.org/wiki/Software_development_kit SDKs].
  * After a user upgrades Xcode, ports can [https://trac.macports.org/ticket/56458 mysteriously stop building correctly].
  * If the Xcode versions of the user and buildbot are different, ports can [https://trac.macports.org/ticket/59078 fail to build correctly].


== Environment Variables ==

To a limited extent, the behavior of compilers can also be controlled with [https://en.wikipedia.org/wiki/Environment_variable environment variables] instead of switches.
||= Switch =||= Variable =||= Affect =||= Notes =||
|| `-I` || CPATH || treated as a delimited list of paths to be added to the default system include path list || ||
|| `-L` || LIBRARY_PATH || tries the directories specified when searching for special linker files  || ||
|| `-mmacosx-version-min` || MACOSX_DEPLOYMENT_TARGET || the default deployment target  || ||
|| `-isysroot`, `-Wl,-syslibroot` || SDKROOT || specifies the SDK  || ||
|| || DEVELOPER_DIR || tells `xcrun` where to search for development tools and properties ||   ||
|| || CC_PRINT_OPTIONS || like `-v` but logs the commands || [https://github.com/macports/macports-base/pull/163 interferes] with`-v`  ||
|| || CC_PRINT_OPTIONS_FILE || the file to log CC_PRINT_OPTIONS output to || ||

Using environment variables can alleviate some of the problems with switches.\\
* They are less likely to be “baked in” the installed files.
* Directories in CPATH and LIBRARY_PATH are searched **after** those specified by the command line options.
However, an environment variable is no panacea.
* Not all build systems [https://github.com/macports/macports-ports/pull/5385 respect environment variables].
* Not all environment variables are supported on all compilers.
* Setting CC_PRINT_OPTIONS causes `-v` to behave differently. For example, it breaks FindOpenMP in CMake.

||= Variable =||= Xcode Support =||= Clang Support =||= GCC Support =||
|| CPATH || all except early versions of Clang (1.*) || all available on MacPorts || all available on MacPorts ||
|| LIBRARY_PATH || all except early versions of Clang (1.*) || all available on MacPorts || all available on MacPorts ||
|| MACOSX_DEPLOYMENT_TARGET || all except early versions of Clang (1.*) || all available on MacPorts || all available on MacPorts ||
|| SDKROOT || OSX 10.9 (existence of /usr/lib/libxcselect.dylib) || ??? || [https://github.com/macports/macports-ports/commit/1850136d289019f3b29a5b24d3ec8ef9b23913ee version 9+] ||
|| DEVELOPER_DIR || OSX 10.9 (existence of /usr/lib/libxcselect.dylib) || ??? || - ||
|| CC_PRINT_OPTIONS || ??? || ??? || ??? ||
|| CC_PRINT_OPTIONS_FILE || ??? || ??? || ??? ||