improve cuda documentation (#101)

* add cuda devlink warning

* add cuda devlink warning

* update cuda setting document

guide/project_examples.md

@@ -704,12 +704,15 @@ target("cuda_console")
 ```
 
 !> Starting with v2.2.7, the default build will enable device-link. (see [Separate Compilation and Linking of CUDA C++ Device Code](https://devblogs.nvidia.com/separate-compilation-linking-cuda-device-code/))
-If you want to disable device-link, you can set it with `add_values("cuda.devlink", false)`.
+If you want to disable device-link, you can set it with `add_values("cuda.build.devlink", false)`.
 
-xmake will detect Cuda SDK automatically and we can also set the SDK directory manually.
+!> Device functions in cuda source files should be device-linked once and only once. On targets with kind `binary` or `shared` xmake will automatically perform the device-link which takes the static libraries they depend into account, while for `static` targets by default will not be device-linked. However, if the final `binary` or `shared` target do not contain any cuda files, the device-link stage could be missing, resulting in an undefined reference error. In this case the static target should be set `add_values("cuda.build.devlink", true)` manually.
+
+xmake will detect Cuda SDK automatically and we can also set the SDK directory (or SDK version for default installations) manually.
 
 ```console
 $ xmake f --cuda=/usr/local/cuda-9.1/
+$ xmake f --cuda=9.1
 $ xmake
 ```
 

zh-cn/guide/project_examples.md

@@ -710,12 +710,15 @@ target("cuda_console")
 ```
 
 !> 从v2.2.7版本开始，默认构建会启用device-link。（参见 [Separate Compilation and Linking of CUDA C++ Device Code](https://devblogs.nvidia.com/separate-compilation-linking-cuda-device-code/)）
-如果要显示禁用device-link，可以通过`add_values("cuda.devlink", false)` 来设置。
+如果要显式禁用device-link，可以通过 `add_values("cuda.devlink", false)` 来设置。
 
-默认会自动探测cuda环境，当然也可以指定Cuda SDK环境目录：
+!> cuda 源文件中的 device 函数需要被 device-link 且只 device-link 一次。在 `shared` 或 `binary` 的 target 上 xmake 会自动进行 device-link ，这时它们依赖的 `static` target 也会同时被 device-link ，因此默认情况下 `static` target 不会被 device-link。然而，如果最终的 `shared` 或 `binary` 的 target 不包含任何 cuda 源文件，则不会发生 device-link 阶段，导致出现 undefined reference 错误。这种情况下，需要手动为 `static` target 指定 `add_values("cuda.build.devlink", true)`.
+
+默认会自动探测cuda环境，当然也可以指定Cuda SDK环境目录，或者指定cuda版本（此时将在默认安装目录进行查找）：
 
 ```console
 $ xmake f --cuda=/usr/local/cuda-9.1/
+$ xmake f --cuda=9.1
 $ xmake
 ```