From 60086a06acdc5e983f8d2152d516849289841453 Mon Sep 17 00:00:00 2001
From: zakuro <z@kuro.red>
Date: Sat, 26 Dec 2020 05:41:22 +0900
Subject: [PATCH] doc: add description for environment-specific files like
 default.c.v, linux.c.v etc (#7543)

---
 doc/docs.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/doc/docs.md b/doc/docs.md
index aecf54f67f..c2a1e82b95 100644
--- a/doc/docs.md
+++ b/doc/docs.md
@@ -2908,6 +2908,8 @@ use `v help`, `v help build` and `v help build-c`.
 
 ## Conditional compilation
 
+### Compile time if
+
 ```v
 // Support for multiple conditions in one branch
 $if ios || android {
@@ -2955,6 +2957,52 @@ Full list of builtin options:
 | `gnu`, `hpux`, `haiku`, `qnx` | `cplusplus`       | `big_endian`          | |
 | `solaris`, `linux_or_macos`   | | | |
 
+### Environment specific files
+
+If a file has an environment-specific suffix, it will only be compiled for that environment.
+
+- `.js.v` => will be used only by the JS backend. These files can contain JS. code.
+- `.c.v` => will be used only by the C backend. These files can contain C. code.
+- `.x64.v` => will be used only by V's x64 backend.
+- `_nix.c.v` => will be used only on Unix systems (non Windows).
+- `_${os}.c.v` => will be used only on the specific `os` system. 
+For example, `_windows.c.v` will be used only when compiling on Windows, or with `-os windows`.
+- `_default.c.v` => will be used only if there is NOT a more specific platform file. 
+For example, if you have both `file_linux.c.v` and `file_default.c.v`, 
+and you are compiling for linux, then only `file_linux.c.v` will be used, 
+and `file_default.c.v` will be ignored.
+
+Here is a more complete example:
+main.v:
+```v ignore
+module main
+fn main() { println(message) }
+```
+
+main_default.c.v:
+```v ignore
+module main
+const ( message = 'Hello world' )
+```
+
+main_linux.c.v:
+```v ignore
+module main
+const ( message = 'Hello linux' )
+```
+
+main_windows.c.v:
+```v ignore
+module main
+const ( message = 'Hello windows' )
+```
+
+With the example above:
+- when you compile for windows, you will get 'Hello windows'
+- when you compile for linux, you will get 'Hello linux'
+- when you compile for any other platform, you will get the 
+non specific 'Hello world' message.
+
 ## Compile time pseudo variables
 
 V also gives your code access to a set of pseudo string variables,