add guide and plugin

1 files changed, 340 insertions, 0 deletions

diff --git a/guide/configuration.md b/guide/configuration.md
new file mode 100644
index 00000000..fef1ad8f
--- /dev/null
+++ b/guide/configuration.md
@@ -0,0 +1,340 @@
+
+Set compilation configuration before building project with command `xmake f|config`.
+
+And if you want to known more options, please run: `xmake f --help`。
+
+<p class="tip">
+    You can use short or long command option, for exmaple: <br>
+    `xmake f` or `xmake config`.<br>
+    `xmake f -p linux` or `xmake config --plat=linux`.
+</p>
+
+## Target Platforms
+
+### Current Host
+
+```bash
+$ xmake
+```
+
+<p class="tip">
+    XMake will detect the current host platform automatically and build project.
+</p>
+
+### Linux
+
+```bash
+$ xmake f -p linux [-a i386|x86_64]
+$ xmake
+```
+
+### Android
+
+```bash
+$ xmake f -p android --ndk=~/files/android-ndk-r10e/ [-a armv5te|armv6|armv7-a|armv8-a|arm64-v8a]
+$ xmake
+```
+
+If you want to set the other android toolchains, you can use [--bin](#-bin) option.
+
+For example:
+
+```bash
+$ xmake f -p android --ndk=~/files/android-ndk-r10e/ -a arm64-v8a --bin=~/files/android-ndk-r10e/toolchains/aarch64-linux-android-4.9/prebuilt/darwin-x86_64/bin
+```
+
+The [--bin](#-bin) option is used to set `bin` directory of toolchains.
+    
+<p class="tip">
+Please attempt to set `--arch=` option if it had failed to check compiler.
+</p>
+
+### iPhoneOS
+
+```bash
+$ xmake f -p iphoneos [-a armv7|armv7s|arm64|i386|x86_64]
+$ xmake
+```
+
+### Windows
+
+```bash
+$ xmake f -p windows [-a x86|x64]
+$ xmake
+```
+
+### Mingw
+
+```bash
+$ xmake f -p mingw --sdk=/usr/local/i386-mingw32-4.3.0/ [-a i386|x86_64]
+$ xmake
+``` 
+
+### Apple WatchOS
+
+```bash
+$ xmake f -p watchos [-a i386|armv7k]
+$ xmake
+```
+
+### Cross Compilation
+
+For linux platform:
+
+```bash
+$ xmake f -p linux --sdk=/usr/local/arm-linux-gcc/ [--bin=/sdk/bin] [--cross=arm-linux-]
+$ xmake
+``` 
+
+Fro other cross platform:
+
+```bash
+$ xmake f -p cross --sdk=/usr/local/arm-xxx-gcc/ [--bin=/sdk/bin] [--cross=arm-linux-]
+$ xmake
+``` 
+
+For custem cross platform (`is_plat("myplat")`):
+
+```bash
+$ xmake f -p myplat --sdk=/usr/local/arm-xxx-gcc/ [--bin=/sdk/bin] [--cross=arm-linux-]
+$ xmake
+``` 
+
+| Configuration Option         | Description                                  |
+| ---------------------------- | -------------------------------------------- |
+| [--sdk](#-sdk)               | Set the sdk root directory of toolchains     |
+| [--bin](#-bin)               | Set the `bin` directory of toolchains        |
+| [--cross](#-cross)           | Set the prefix of compilation tools          |
+| [--as](#-as)                 | Set `asm` assembler                          |
+| [--cc](#-cc)                 | Set `c` compiler                             |
+| [--cxx](#-cxx)               | Set `c++` compiler                           |
+| [--mm](#-mm)                 | Set `objc` compiler                          |
+| [--mxx](#-mxx)               | Set `objc++` compiler                        |
+| [--sc](#-sc)                 | Set `swift` compiler                         |
+| [--gc](#-gc)                 | Set `golang` compiler                        |
+| [--dc](#-dc)                 | Set `dlang` compiler                         |
+| [--rc](#-rc)                 | Set `rust` compiler                          |
+| [--cu](#-cu)                 | Set `cuda` compiler                          |
+| [--ld](#-ld)                 | Set `c/c++/objc/asm` linker                  |
+| [--sh](#-sh)                 | Set `c/c++/objc/asm` shared library linker   |
+| [--ar](#-ar)                 | Set `c/c++/objc/asm` static library archiver |
+| [--sc-ld](#-sc-ld)           | Set `swift` linker                           |
+| [--sc-sh](#-sc-sh)           | Set `swift` shared library linker            |
+| [--gc-ld](#-gc-ld)           | Set `golang` linker                          |
+| [--gc-ar](#-gc-ar)           | Set `golang` static library archiver         |
+| [--dc-ld](#-dc-ld)           | Set `dlang` linker                           |
+| [--dc-sh](#-dc-sh)           | Set `dlang` shared library linker            |
+| [--dc-ar](#-dc-ar)           | Set `dlang` static library archiver          |
+| [--rc-ld](#-rc-ld)           | Set `rust` linker                            |
+| [--rc-sh](#-rc-sh)           | Set `rust` shared library linker             |
+| [--rc-ar](#-rc-ar)           | Set `rust` static library archiver           |
+| [--cu-cxx](#-cu-cxx)         | Set `cuda` host compiler                     |
+| [--cu-ld](#-cu-ld)           | Set `cuda` linker                            |
+| [--asflags](#-asflags)       | Set `asm` assembler option                   |
+| [--cflags](#-cflags)         | Set `c` compiler option                      |
+| [--cxflags](#-cxflags)       | Set `c/c++` compiler option                  |
+| [--cxxflags](#-cxxflags)     | Set `c++` compiler option                    |
+| [--mflags](#-mflags)         | Set `objc` compiler option                   |
+| [--mxflags](#-mxflags)       | Set `objc/c++` compiler option               |
+| [--mxxflags](#-mxxflags)     | Set `objc++` compiler option                 |
+| [--scflags](#-scflags)       | Set `swift` compiler option                  |
+| [--gcflags](#-gcflags)       | Set `golang` compiler option                 |
+| [--dcflags](#-dcflags)       | Set `dlang` compiler option                  |
+| [--rcflags](#-rcflags)       | Set `rust` compiler option                   |
+| [--cuflags](#-cuflags)       | Set `cuda` compiler option                   |
+| [--ldflags](#-ldflags)       | Set  linker option                           |
+| [--shflags](#-shflags)       | Set  shared library linker option            |
+| [--arflags](#-arflags)       | Set  static library archiver option          |
+
+<p class="tip">
+if you want to known more options, please run: `xmake f --help`。
+</p>
+
+#### --sdk
+
+- Set the sdk root directory of toolchains
+
+xmake provides a convenient and flexible cross-compiling support.
+In most cases, we need not to configure complex toolchains prefix, for example: `arm-linux-`
+
+As long as this toolchains meet the following directory structure:
+
+```
+/home/toolchains_sdkdir
+   - bin
+       - arm-linux-gcc
+       - arm-linux-ld
+       - ...
+   - lib
+       - libxxx.a
+   - include
+       - xxx.h
+```
+
+Then，we can only configure the sdk directory and build it.
+
+```bash
+$ xmake f -p linux --sdk=/home/toolchains_sdkdir
+$ xmake
+```
+
+xmake will detect the prefix: arm-linux- and add the include and library search directory automatically.
+
+```
+-I/home/toolchains_sdkdir/include -L/home/toolchains_sdkdir/lib
+```
+
+#### --bin
+
+- Set the `bin` directory of toolchains
+
+We need set it manually if the toolchains /bin directory is in other places, for example:
+
+```bash
+$ xmake f -p linux --sdk=/home/toolchains_sdkdir --bin=/usr/opt/bin
+$ xmake
+```
+
+<p class="tips">
+Before v2.2.1 version, this parameter name is `--toolchains`, exists more ambiguous, so we changed to `--bin=` to set the bin directory.
+</p>
+
+#### --cross
+
+- Set the prefix of compilation tools
+
+For example, under the same toolchains directory at the same time, there are two different compilers:
+
+```
+/opt/bin
+ - armv7-linux-gcc
+ - aarch64-linux-gcc
+```
+
+If we want to use the `armv7-linux-gcc` compiler, we can run the following command:
+
+```bash
+$ xmake f -p linux --sdk=/usr/toolsdk --bin=/opt/bin --cross=armv7-linux-
+```
+
+#### --as
+
+- Set `asm` assembler
+
+```bash
+$ xmake f -p linux --sdk=/user/toolsdk --as=armv7-linux-as
+```
+
+If the 'AS' environment variable exists, it will use the values specified in the current environment variables.
+
+<p class="tips">
+We can set a unknown compiler as like-gcc/clang compiler, .e.g `xmake f --as=gcc@/home/xxx/asmips.exe` 
+</p>
+
+#### --cc
+
+- Set c compiler
+
+```bash
+$ xmake f -p linux --sdk=/user/toolsdk --cc=armv7-linux-clang
+```
+
+If the 'CC' environment variable exists, it will use the values specified in the current environment variables.
+
+<p class="tips">
+We can set a unknown compiler as like-gcc/clang compiler, .e.g `xmake f --cc=gcc@/home/xxx/ccmips.exe` 
+</p>
+
+#### --cxx
+
+- Set `c++` compiler
+
+```bash
+$ xmake f -p linux --sdk=/user/toolsdk --cxx=armv7-linux-clang++
+```
+
+If the 'CXX' environment variable exists, it will use the values specified in the current environment variables.
+
+<p class="tips">
+We can set a unknown compiler as like-gcc/clang compiler, .e.g `xmake f --cxx=g++@/home/xxx/c++mips.exe` 
+</p>
+
+#### --ld
+
+- Set `c/c++/objc/asm` linker
+
+```bash
+$ xmake f -p linux --sdk=/user/toolsdk --ld=armv7-linux-clang++
+```
+
+If the 'LD' environment variable exists, it will use the values specified in the current environment variables.
+
+<p class="tips">
+We can set a unknown compiler as like-gcc/clang linker, .e.g `xmake f --ld=g++@/home/xxx/c++mips.exe` 
+</p>
+
+#### --sh
+
+- Set `c/c++/objc/asm` shared library linker
+
+```bash
+$ xmake f -p linux --sdk=/user/toolsdk --sh=armv7-linux-clang++
+```
+
+If the 'SH' environment variable exists, it will use the values specified in the current environment variables.
+
+<p class="tips">
+We can set a unknown compiler as like-gcc/clang linker, .e.g `xmake f --sh=g++@/home/xxx/c++mips.exe` 
+</p>
+
+#### --ar
+
+- Set `c/c++/objc/asm` static library archiver
+
+```bash
+$ xmake f -p linux --sdk=/user/toolsdk --ar=armv7-linux-ar
+```
+
+If the 'AR' environment variable exists, it will use the values specified in the current environment variables.
+
+<p class="tips">
+We can set a unknown compiler as like-ar archiver, .e.g `xmake f --ar=ar@/home/xxx/armips.exe` 
+</p>
+
+## Global Configuration
+
+You can save to the global configuration for simplfying operation.
+
+For example:
+
+```bash
+$ xmake g --ndk=~/files/android-ndk-r10e/
+```
+
+Now, we config and build project for android again.
+
+```bash
+$ xmake f -p android
+$ xmake
+```
+
+<p class="tip">
+    You can use short or long command option, for exmaple: `xmake g` or `xmake global`.<br>
+</p>
+
+## Clean Configuration
+
+We can clean all cached configuration and re-configure projecct.
+
+```bash
+$ xmake f -c
+$ xmake
+```
+
+or 
+
+```bash
+$ xmake f -p iphoneos -c
+$ xmake
+```
+