From 04ef7ec45d2a6b1f008b8cb52314ae0e71f16fa3 Mon Sep 17 00:00:00 2001
From: Jussi Pakkanen <jpakkane@gmail.com>
Date: Sat, 19 Feb 2022 18:17:28 +0200
Subject: Add new env2mfile command.

---
 docs/markdown/Commands.md           | 29 +++++++++++++++++++++++++++
 docs/markdown/snippets/env2mfile.md | 40 +++++++++++++++++++++++++++++++++++++
 2 files changed, 69 insertions(+)
 create mode 100644 docs/markdown/snippets/env2mfile.md

(limited to 'docs/markdown')

diff --git a/docs/markdown/Commands.md b/docs/markdown/Commands.md
index 3542aa4..f905d2c 100644
--- a/docs/markdown/Commands.md
+++ b/docs/markdown/Commands.md
@@ -150,6 +150,35 @@ Create a project in `sourcedir`:
 meson init -C sourcedir
 ```
 
+### env2mfile
+
+*This command is experimental and subject to change.*
+
+*{Since 0.62.0}*
+
+{{ env2mfile_usage.inc }}
+
+Create native and cross files from the current environment, typically
+by sniffing environment variables like `CC` and `CFLAGS`.
+
+{{ env2mfile_arguments.inc }}
+
+#### Examples:
+
+Autodetect the current cross build environment:
+
+```
+meson env2mfile --cross -o current_cross.txt --cpu=arm7a --cpu-family=arm --system=linux
+```
+
+Generate a cross build using Debian system information:
+
+```
+meson env2mfile --cross --debarch=armhf -o deb_arm_cross.txt
+```
+
+
+
 ### introspect
 
 {{ introspect_usage.inc }}
diff --git a/docs/markdown/snippets/env2mfile.md b/docs/markdown/snippets/env2mfile.md
new file mode 100644
index 0000000..a575618
--- /dev/null
+++ b/docs/markdown/snippets/env2mfile.md
@@ -0,0 +1,40 @@
+## Experimental command to convert environments to cross files
+
+Meson has a new command `env2mfile` that can be used to convert
+"environment variable based" cross and native compilation environments
+to Meson machine files. This is especially convenient for e.g. distro
+packagers so they can easily generate unambiguous configuration files
+for packge building.
+
+As an example here's how you would generate a cross file that takes
+its settings from the `CC`, `CXX`, `CFLAGS` etc environment variables.
+
+    meson env2mfile --cross --system=baremetal --cpu=armv7 --cpu-family=arm -o armcross.txt
+
+The command also has support for generating Debian build files using
+system introspection:
+
+    meson env2mfile --cross --debarch armhf -o debarmhf_cross.txt
+
+Note how you don't need to specify any system details, the command
+gets them transparently via `dpkg-architecture`.
+
+Creating a native file is done in the same way:
+
+    meson env2mfile --native -o current_system.txt
+
+This system will detect if the `_FOR_BUILD` environment variables are
+enabled and then uses them as needed.
+
+With this you should be able to convert any envvar-based cross build
+setup to cross and native files and then use those. This means, among
+other things, that you can then run your compilations from any shell,
+not just the special one that has all the environment variables set.
+
+As this functionality is still a bit in flux, the specific behaviour
+and command line arguments to use are subject to change. Because of
+this the main documentation has not yet been updated.
+
+Please try this for your use cases and report to us if it is working.
+Patches to make the autodetection work on other distros and platforms
+are also welcome.
-- 
cgit v1.1