Merge pull request #4744 from dcbaker/docs-cflags

Discourage the use of env variables like CFLAGS [skip ci]

docs/markdown/Porting-from-autotools.md

@@ -450,9 +450,9 @@ AM_CPPFLAGS =                                                   \
 `meson.build`:
 
 ```meson
-add_global_arguments('-DG_LOG_DOMAIN="As"', language : 'c')
-add_global_arguments('-DAS_COMPILATION', language : 'c')
-add_global_arguments('-DLOCALSTATEDIR="/var"', language : 'c')
+add_project_arguments('-DG_LOG_DOMAIN="As"', language : 'c')
+add_project_arguments('-DAS_COMPILATION', language : 'c')
+add_project_arguments('-DLOCALSTATEDIR="/var"', language : 'c')
 ```
 
 ### Tests

docs/markdown/Quick-guide.md

@@ -82,7 +82,7 @@ build and install Meson projects are the following.
 
 ```console
 $ cd /path/to/source/root
-$ CFLAGS=... CXXFLAGS=... LDFLAGS=.. meson --prefix /usr --buildtype=plain builddir
+$ meson --prefix /usr --buildtype=plain builddir -Dc_args=... -Dcpp_args=... -Dc_link_args=... -Dcpp_link_args=...
 $ ninja -v -C builddir
 $ ninja -C builddir test
 $ DESTDIR=/path/to/staging/root ninja -C builddir install

docs/markdown/Reference-tables.md

@@ -99,24 +99,30 @@ future releases.
 
 These are the parameter names for passing language specific arguments to your build target.
 
-| Language      | Parameter name |
-| -----         | ----- |
-| C             | c_args |
-| C++           | cpp_args |
-| C#            | cs_args |
-| D             | d_args |
-| Fortran       | fortran_args |
-| Java          | java_args |
-| Objective C   | objc_args |
-| Objective C++ | objcpp_args |
-| Rust          | rust_args |
-| Vala          | vala_args |
+| Language      | compiler name | linker name       |
+| ------------- | ------------- | ----------------- |
+| C             | c_args        | c_link_args       |
+| C++           | cpp_args      | cpp_link_args     |
+| C#            | cs_args       | cs_link_args      |
+| D             | d_args        | d_link_args       |
+| Fortran       | fortran_args  | fortran_link_args |
+| Java          | java_args     | java_link_args    |
+| Objective C   | objc_args     | objc_link_args    |
+| Objective C++ | objcpp_args   | objcpp_link_args  |
+| Rust          | rust_args     | rust_link_args    |
+| Vala          | vala_args     | vala_link_args    |
 
 ## Compiler and linker flag environment variables
 
 These environment variables will be used to modify the compiler and
 linker flags.
 
+It is recommended that you **do not use these**. They are provided purely to
+for backwards compatibility with other build systems. There are many caveats to
+their use, especially when rebuilding the project. It is **highly** recommended
+that you use [the command line arguments](#language-arguments-parameters-names)
+instead.
+
 | Name      | Comment                                  |
 | -----     | -------                                  |
 | CFLAGS    | Flags for the C compiler                 |

docs/markdown/howtox.md

@@ -52,7 +52,9 @@ executable(..., dependencies : thread_dep)
 
 ## Set extra compiler and linker flags from the outside (when e.g. building distro packages)
 
-The behavior is the same as with other build systems, with environment variables during first invocation.
+The behavior is the same as with other build systems, with environment
+variables during first invocation. Do not use these when you need to rebuild
+the source
 
 ```console
 $ CFLAGS=-fsomething LDFLAGS=-Wl,--linker-flag meson <options>