# CUDA 项目

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/zh-cn/help/clion/llms.txt).

> **TL;DR**
> 操作系统  ：Linux / Windows（仅限 MSVC）
>
>
>
> 必需工具：   [CUDA Development Toolkit](https://developer.nvidia.com/cuda-downloads)
>
>
>
> CUDA 项目格式：   CMake

[CUDA](https://developer.nvidia.com/cuda-zone)（统一计算设备架构）是由 NVidia 提供的并行计算平台和编程模型。 它为支持 CUDA 的 GPU 提供了 C/C++ 语言扩展和 API。

CLion 支持 CUDA C/C++ 并为其提供了 [代码洞察](#code-insight)。 此外，CLion 可以通过新建项目向导帮助您 [创建](#new-prj)基于 CMake 的 CUDA 应用程序。

## CLion 中的 CUDA 项目

在开始之前，请确保安装了 [CUDA Development Toolkit](https://developer.nvidia.com/cuda-downloads)。 有关安装过程的更多信息，请参阅 [官方文档](https://docs.nvidia.com/cuda/cuda-quick-start-guide/index.html)。

Procedure: 创建一个新的 CUDA 项目

1. 在主菜单中，转到  `文件 | 新建项目` 并选择   CUDA 可执行文件  或   CUDA 库  作为您的项目类型。

2. 根据需要指定项目位置、语言标准和库类型。

![创建一个新的 CUDA 项目](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cuda_createprj.png)

所选标准将设置为  `CMAKE_CUDA_STANDARD` 变量。 如果您计划向项目中添加其他标准的常规 C/C++ 文件，则需要在  `CMakeLists.txt` 脚本中手动设置  `CMAKE_C_STANDARD` /  `CMAKE_CXX_STANDARD` 变量。

3. 点击   创建  ，CLion 将生成一个包含示例  `CMakeLists.txt` 和  `main.cu` 的项目：

![一个模板 CUDA 项目](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cuda_emptyprj.png)

> **Tip:**
> 您可以在  `设置 | 编辑器 | 文件和代码模板` 的   其他  选项卡中编辑 CUDA 项目的  `CMakeLists.txt` 模板。 有关更多信息，请参阅 [CMakeLists.txt 文件模板](cmakelists-txt-file.html#cmakelist-template)。

Procedure: 打开一个已有的 CUDA 项目

* 基于 CMake 的 CUDA 项目可以作为常规 CMake 应用程序从  `文件 | 打开` 菜单或 CLion 欢迎界面 [打开](creating-new-project-from-scratch.html#open-prj)。

* 对于非 CMake 的 CUDA 项目，您可以 [生成](compilation-database.html#compdb_generate)一个   编译数据库  ，然后在 CLion 中 [加载](compilation-database.html#compdb_load)它。

Procedure: 添加新的 .cu/.cuh 文件

1. 右键点击项目树中的目标文件夹，然后选择  `新建 | C/C++ 源文件` 或  `C/C++ 头文件` 。

2. 在   Type  字段中，为 CUDA 源文件或 CUDA 头文件分别选择   .cu  或   .cuh  。

如果希望新文件自动添加到一个或多个 CMake 目标中，请选中   添加到目标  复选框并从列表中选择所需的目标。

![添加一个 CUDA 源文件](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cuda_addfile.png)

选项将包括常规 CMake 目标和使用  `cuda_add_executable` /  `cuda_add_library` 创建的目标（请参阅 [CUDA CMake 语言](#cuda-lang)）。

Procedure: 设置 CUDA 编译器

> **Note:**
> 在 Windows 上，CUDA 项目只能使用 [Microsoft Visual C++](quick-tutorial-on-configuring-clion-on-windows.html#MSVC)工具链进行开发。 检查工具链设置以确保所选架构与已安装的 CUDA 工具包的架构匹配（通常为   amd64  ）。

所有  `.cu` /  `.cuh` 文件必须使用 [NVCC](https://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/index.html)（基于 LLVM 的 CUDA 编译器驱动程序）进行编译。

为了检测 NVCC，CMake 需要知道 CUDA 工具链的位置。 使用以下选项之一：

* 在  system   `PATH` 变量中设置 CUDA 工具链路径。

在   Linux  上，建议将  `/usr/local/cuda-<version>/bin` 添加到  `PATH` 中的  `/etc/environment` 配置文件。 这样，无论您是从终端工作、使用桌面启动器，还是连接到远程 Linux 机器，CUDA 工具包的位置都将可用。 有关更多信息，请参阅官方 [Linux 安装指南](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html#environment-setup)。

* 或者，在 CMake 中指定 NVCC 的路径。 其中一种方法是将  `CMAKE_CUDA_COMPILER` 变量设置为 NVCC 可执行文件的位置。

您可以将此变量添加到  `CMakeLists.txt` ，或者使用   CMake 选项  字段中的  `设置 | 构建、执行、部署 | CMake` 。 例如，在 Windows 上：

![CUDA 项目的 CMake 设置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cuda_cmakesettings.png)

Procedure: 配置非默认的主机编译器

为了编译主机代码，NVCC 调用系统的默认 C++ 编译器（在 Linux 上为   gcc  /   g++  ，在 Windows 上为   cl.exe  ）。 您可以在官方 [Windows](https://docs.nvidia.com/cuda/cuda-installation-guide-microsoft-windows/index.html)和 [Linux](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html)指南中检查支持的版本。

如果系统的默认编译器与您的 CUDA 工具包不兼容，您可以为 NVCC 指定一个自定义的编译器可执行文件。

Linux:

选择以下选项之一：

1.

使用  `CUDAHOSTCXX` 环境变量

```CMAKE
CUDAHOSTCXX=/path/to/compiler
```

* 仅为当前项目设置时，请在 `设置 | 构建、执行、部署 | CMake` 的 环境 字段中使用它。

* 要使设置系统作用域有效，请在 `/etc/environment` 中添加此变量。

2.

使用 CMake 变量

* 对于使用 [CUDA 作为语言](#cuda-lang)的 CUDA 项目： CMAKE_CUDA_HOST_COMPILER 和 CMAKE_CUDA_FLAGS

* 对于使用 `find_package(CUDA)` 的 CUDA 项目： CUDA_HOST_COMPILER 和 CUDA_NVCC_FLAGS

将以下行添加到  `设置 | 构建、执行、部署 | CMake` 的   CMake 选项  字段中：

```CMAKE
-DCMAKE_CUDA_HOST_COMPILER=/path/to/compiler
-DCMAKE_CUDA_FLAGS="-ccbin /path/to/compiler"

```

或者，在  `CMakeLists.txt` 中设置变量。

> **Note:**
> 确保将这些行放在  `project()` 命令之前。

```CMAKE
set(CMAKE_CUDA_HOST_COMPILER "/path/to/compiler")
set(CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} -ccbin /path/to/compiler")

```

要使用工具链的编译器，请将路径替换为  `${CMAKE_CXX_COMPILER}` ：

```CMAKE
set(CMAKE_CUDA_HOST_COMPILER "${CMAKE_CXX_COMPILER}")
set(CMAKE_CUDA_FLAGS "${CMAKE_CUDA_FLAGS} -ccbin ${CMAKE_CXX_COMPILER}")

```

Windows:

在 Windows 上，当您在 [MSVC 工具链](quick-tutorial-on-configuring-clion-on-windows.html#MSVC)中切换 Visual Studio 安装时，主机编译器会自动更改。

## CUDA 项目的 CMake

### CUDA 语言

从 CMake 3.8 版本开始，CUDA 被支持作为一种语言。 请注意 CLion 为新 CUDA 项目生成的  `CMakeLists.txt` 脚本开头的以下行：

```CMAKE
project(cuda_testprj CUDA)
```

在此命令中，  `CUDA` 被指定为 [LANGUAGES](https://cmake.org/cmake/help/latest/command/project.html#options)选项（为了缩短行，省略了  LANGUAGES 关键字）。

例如，您可以编写  `project(project_name LANGUAGES CUDA CXX)` 以同时启用 CUDA 和 C++ 作为项目语言。

> **Note:**
> 在 3.8 版本之前，CUDA 是通过 [FindCUDA](https://cmake.org/cmake/help/latest/module/FindCUDA.html)模块在 CMake 中支持的。 尽管您仍然可以使用 FindCUDA，但请注意，自 CMake 3.10 起，它已被正式弃用。

### NVCC 编译器选项

要为 NVCC 指定 [编译器标志](https://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/index.html#nvcc-command-options)，请设置 [CMAKE_CUDA_FLAGS](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html#variable:CMAKE_%3CLANG%3E_FLAGS)变量：

```CMAKE
set(CMAKE_CUDA_FLAGS "-Wall")
```

这样，标志将全局用于所有目标。

另一种方法是使用 [target_compile_options](https://cmake.org/cmake/help/latest/command/target_compile_options.html)命令为特定目标设置标志。 例如：

```CMAKE
target_compile_options(
    my_target PRIVATE $<$<COMPILE_LANGUAGE:CUDA>:
    --generate-line-info>)
                
```

### 可分离编译

默认情况下，NVCC 使用全程序编译方法，但您可以启用 [可分离编译](https://devblogs.nvidia.com/separate-compilation-linking-cuda-device-code/)。 这样，CUDA 项目的组件将被编译为单独的对象。

您可以通过 [CMAKE_CUDA_SEPARABLE_COMPILATION](https://cmake.org/cmake/help/latest/variable/CMAKE_CUDA_SEPARABLE_COMPILATION.html#variable:CMAKE_CUDA_SEPARABLE_COMPILATION)变量控制可分离编译。

* 添加 `set(CMAKE_CUDA_SEPARABLE_COMPILATION ON)` 命令以全局启用它。

* 使用 [CUDA_SEPARABLE_COMPILATION](https://cmake.org/cmake/help/latest/prop_tgt/CUDA_SEPARABLE_COMPILATION.html#prop_tgt:CUDA_SEPARABLE_COMPILATION)属性为特定目标启用它： ```CMAKE set_target_properties( cuda_testprj PROPERTIES CUDA_SEPARABLE_COMPILATION ON) ```

### 添加目标

当 CUDA 被启用为一种语言时，您可以使用常规  `add_executable` /  `add_library` 命令创建包含 CUDA 代码的可执行文件和库：

```CMAKE
add_executable(target_name cpp_file.cpp cuda_file.cu)
```

另一种选择是在添加新文件时添加 CUDA 目标。 点击   添加新目标  ，然后从下拉列表中选择所需的命令：

![为新文件添加目标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cuda_addingtargets.png)

CMake 将根据文件扩展名调用适当的编译器。

> **Note:**
> 请注意，FindCUDA 命令  `cuda_add_executable` /  `cuda_add_library` 不再需要。

## CUDA C/C++ 的代码洞察

> **Tip:**
> 下图展示了以 [ClaraGenomicsAnalysis](https://github.com/clara-genomics/ClaraGenomicsAnalysis)项目为例的 CUDA 代码洞察。

CLion 解析并正确高亮显示 CUDA 代码，这意味着 [导航](navigating-through-the-source-code.html)、 [快速文档](viewing-inline-documentation.html)和其他代码辅助功能按预期工作：

![CUDA 代码的代码洞察](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cuda_codeinsight.png)

此外， [代码补全](auto-completing-code.html)可用于内核调用中的尖括号。

![CUDA 代码的补全](https://resources.jetbrains.com/help/img/idea/2026.3/cl_cuda_kernelcompletion.png)

## 使用 cuda-gdb 调试

在 Linux 上，您可以使用 [cuda-gdb](https://docs.nvidia.com/cuda/cuda-gdb/index.html)调试 CUDA 内核。

Procedure: 将 cuda-gdb 设置为自定义调试器

1. 转到  `设置 | 构建、执行、部署 | 工具链` ，并在当前工具链的   调试器  字段中提供路径。

2. 使用  `-G` 编译器选项添加 CUDA 调试符号：  `add_compile_options(-G)` 。 您可以在   CMake 选项  的 [profile](cmake-profile.html)或  `CMakeLists.txt` 脚本中添加此命令。

## 已知问题和限制

* 在 Windows 上，CLion 为 MSVC 工具链捆绑的 [基于 LLDB 的调试器](quick-tutorial-on-configuring-clion-on-windows.html#msvc-debugger)可能会与 CUDA 代码存在问题。

* 在 macOS 上，自 10.13 版本起，该平台已被官方停止支持，因此 CLion 对 CUDA 项目的支持尚未经过测试。

* 目前， [代码覆盖率](code-coverage-clion.html)、 [Valgrind Memcheck](memory-profiling-with-valgrind.html) 和 [CPU 分析](cpu-profiler.html)工具在 CUDA 项目中无法正常工作。

## See also

### 快速开始

[快速 CMake 教程](quick-cmake-tutorial.html) [Quick Tutorial on Configuring CLion on Windows](quick-tutorial-on-configuring-clion-on-windows.html)

