Merge pull request #6 from OpportunityLiu/cuda-doc

add docs for find_cudadevices; improve docs for cuda templates

README.md

@@ -222,6 +222,7 @@ Support languages:
 
 * c/c++
 * objc/c++
+* cuda
 * asm
 * swift
 * dlang
@@ -422,20 +423,16 @@ $ xmake
 ```
 
 ```lua
+-- add helper function add_cugencodes
+includes('add_cugencodes.lua')
+-- define target
 target("cuda_console")
     set_kind("binary")
     add_files("src/*.cu")
-
-    -- generate SASS code for each SM architecture
-    for _, sm in ipairs({"30", "35", "37", "50", "52", "60", "61", "70"}) do
-        add_cuflags("-gencode arch=compute_" .. sm .. ",code=sm_" .. sm)
-        add_ldflags("-gencode arch=compute_" .. sm .. ",code=sm_" .. sm)
-    end
-
-    -- generate PTX code from the highest SM architecture to guarantee forward-compatibility
-    sm = "70"
-    add_cuflags("-gencode arch=compute_" .. sm .. ",code=compute_" .. sm)
-    add_ldflags("-gencode arch=compute_" .. sm .. ",code=compute_" .. sm)
+    -- generate SASS code for SM architecture of current host
+    add_cugencodes("native")
+    -- generate PTX code for the virtual architecture to guarantee compatibility
+    add_cugencodes("compute_30")
 ```
 
 xmake will detect Cuda SDK automatically and we can also set the SDK directory manually.
@@ -740,6 +737,7 @@ $ xmake
 | [--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                            |
 | [--cu-sh](#-cu-sh)           | Set `cuda` shared library linker             |
 | [--cu-ar](#-cu-ar)           | Set `cuda` static library archiver           |

manual.md

@@ -7549,6 +7549,7 @@ The interface of this module is spread across multiple module directories, try t
 | [detect.find_package](#detect-find_package) | Find package files, including library files and search paths | >= 2.1.5 |
 | [detect.find_tool](#detect-find_tool) | Find Tool | >= 2.1.5 |
 | [detect.find_toolname](#detect-find_toolname) | Find Tool Name | >= 2.1.5 |
+| [detect.find_cudadevices](#detect-find_cudadevices) | Find CUDA devices of the host                         | >= 2.2.7             |
 | [detect.features](#detect-features) | Get all the features of the specified tool | >= 2.1.5 |
 | [detect.has_features](#detect-has_features) | Determine if the specified feature is supported | >= 2.1.5 |
 | [detect.has_flags](#detect-has_flags) | Determine if the specified parameter options are supported | >= 2.1.5 |
@@ -8113,6 +8114,24 @@ example:
 
 Compared with program, toolname can uniquely mark a tool, and it is also convenient to find and load the corresponding script `find_xxx.lua`.
 
+###### detect.find_cudadevices
+
+- Find CUDA devices of the host
+
+Enumerate CUDA devices through the CUDA Runtime API and query theirs properties.
+
+```lua
+import("lib.detect.find_cudadevices")
+
+local devices = find_cudadevices({ skip_compute_mode_prohibited = true })
+local devices = find_cudadevices({ min_sm_arch = 35, order_by_flops = true })
+```
+
+The result returned is: `{ { ['$id'] = 0, name = "GeForce GTX 960M", major = 5, minor = 0, ... }, ... }`
+
+The included properties will vary depending on the current CUDA version.
+Please refer to [CUDA Toolkit Documentation](https://docs.nvidia.com/cuda/cuda-runtime-api/structcudaDeviceProp.html#structcudaDeviceProp) and its historical version for more information.
+
 ###### detect.features
 
 - Get all the features of the specified tool

zh/README.md

@@ -250,6 +250,7 @@ target("hello")
 
 * c/c++
 * objc/c++
+* cuda
 * asm
 * swift
 * dlang
@@ -452,22 +453,19 @@ $ xmake
 ```
 
 ```lua
+-- add helper function add_cugencodes
+includes('add_cugencodes.lua')
+-- define target
 target("cuda_console")
     set_kind("binary")
     add_files("src/*.cu")
-
-    -- generate SASS code for each SM architecture
-    for _, sm in ipairs({"30", "35", "37", "50", "52", "60", "61", "70"}) do
-        add_cuflags("-gencode arch=compute_" .. sm .. ",code=sm_" .. sm)
-        add_ldflags("-gencode arch=compute_" .. sm .. ",code=sm_" .. sm)
-    end
-
-    -- generate PTX code from the highest SM architecture to guarantee forward-compatibility
-    sm = "70"
-    add_cuflags("-gencode arch=compute_" .. sm .. ",code=compute_" .. sm)
-    add_ldflags("-gencode arch=compute_" .. sm .. ",code=compute_" .. sm)
+    -- generate SASS code for SM architecture of current host
+    add_cugencodes("native")
+    -- generate PTX code for the virtual architecture to guarantee compatibility
+    add_cugencodes("compute_30")
 ```
 
+
 默认会自动探测cuda环境，当然也可以指定Cuda SDK环境目录：
 
 ```console
@@ -772,6 +770,7 @@ $ xmake
 | [--rc-ld](#-rc-ld)           | 设置`rust`链接器                 |
 | [--rc-sh](#-rc-sh)           | 设置`rust`共享库链接器           |
 | [--rc-ar](#-rc-ar)           | 设置`rust`静态库归档器           |
+| [--cu-cxx](#-cu-cxx)         | 设置`cuda` host编译器            |
 | [--cu-ld](#-cu-ld)           | 设置`cuda`链接器                 |
 | [--cu-sh](#-cu-sh)           | 设置`cuda`共享库链接器           |
 | [--cu-ar](#-cu-ar)           | 设置`cuda`静态库归档器           |

zh/manual.md

@@ -7632,6 +7632,7 @@ environment.leave("toolchains")
 | [detect.find_package](#detect-find_package)         | 查找包文件，包含库文件和搜索路径             | >= 2.1.5             |
 | [detect.find_tool](#detect-find_tool)               | 查找工具                                     | >= 2.1.5             |
 | [detect.find_toolname](#detect-find_toolname)       | 查找工具名                                   | >= 2.1.5             |
+| [detect.find_cudadevices](#detect-find_cudadevices) | 查找本机的 CUDA 设备                         | >= 2.2.7             |
 | [detect.features](#detect-features)                 | 获取指定工具的所有特性                       | >= 2.1.5             |
 | [detect.has_features](#detect-has_features)         | 判断指定特性是否支持                         | >= 2.1.5             |
 | [detect.has_flags](#detect-has_flags)               | 判断指定参数选项是否支持                     | >= 2.1.5             |
@@ -8162,6 +8163,23 @@ end
 
 toolname相比program，更能唯一标示某个工具，也方便查找和加载对应的脚本`find_xxx.lua`。
 
+###### detect.find_cudadevices
+
+- 查找本机的 CUDA 设备
+
+通过 CUDA Runtime API 枚举本机的 CUDA 设备，并查询其属性。
+
+```lua
+import("lib.detect.find_cudadevices")
+
+local devices = find_cudadevices({ skip_compute_mode_prohibited = true })
+local devices = find_cudadevices({ min_sm_arch = 35, order_by_flops = true })
+```
+
+返回的结果为：`{ { ['$id'] = 0, name = "GeForce GTX 960M", major = 5, minor = 0, ... }, ... }`
+
+包含的属性依据当前 CUDA 版本会有所不同，可以参考 [CUDA 官方文档](https://docs.nvidia.com/cuda/cuda-runtime-api/structcudaDeviceProp.html#structcudaDeviceProp)及其历史版本。
+
 ###### detect.features
 
 - 获取指定工具的所有特性