Improve Clang installation documentation by using a dedicated versioned directory （改进 Clang 安装文档：采用独立版本化目录的方式） #104
Conversation
Clarify the recommended installation method for Clang by using a dedicated directory under /usr/local, instead of copying binaries directly into system paths. Updated PATH explanation, removed unsafe practices, and improved overall clarity and maintainability of the documentation.
docs/Ch03/index.md
Outdated
| ``` | ||
|
|
||
| 这个目录下的 `clang` 和 `clang++` 就类似于我们比较熟悉的 `gcc` 和 `g++`。这两个是可以直接运行进行编译源代码的可执行文件。当然，我们不能每次在需要编译程序的时候输入如此长的路径找到 `clang` 和 `clang++`，而更希望的是能够像 `apt` 那样在任何地方都可以直接运行。我们可以这样做： | ||
| 这个目录下的 `clang` 和 `clang++` 就类似于我们比较熟悉的 `gcc` 和 `g++`。这两个是可以直接运行进行编译源代码的可执行文件。当然，我们不能每次在需要编译程序的时候输入如此长的路径找到 `clang` 和 `clang++`，而更希望的是能够像 `apt` 命令那样在任何地方都可以直接运行。我们可以这样做： |
There was a problem hiding this comment.
这里本来实际要表达的意思是「像 apt 安装的程序那样……直接运行」。
There was a problem hiding this comment.
那这里的原文应该可以更加清楚明白一些，不然会让人产生和我一样的歧义，认为是像运行 apt 命令一样运行其他命令，虽然这个歧义不会影响全文整体的阅读，但我觉得教材类文章更应该精益求精
| (Output omitted) | ||
| ``` | ||
|
|
||
| 这个目录下的 `clang` 和 `clang++` 就类似于我们比较熟悉的 `gcc` 和 `g++`。这两个是可以直接运行进行编译源代码的可执行文件。当然，我们不能每次在需要编译程序的时候输入如此长的路径找到 `clang` 和 `clang++`，而更希望的是能够像 `apt` 那样在任何地方都可以直接运行。我们可以这样做： |
There was a problem hiding this comment.
升级也是有必要的，新版的 Ubuntu/Debian 已经没有 libtinfo.so.5 了。
There was a problem hiding this comment.
在这里提到针对 LLVM 的升级一事，我建议修改为 16 版本，这个版本较为稳定可靠
docs/Ch03/index.md
Outdated
| ``` | ||
|
|
||
| 为什么是 `/usr/local` 呢？因为 `/usr/local/bin` 处在 PATH 环境变量下。当我们在终端输入命令时，终端会先判断是否为终端的内建命令，如果不是，则会在 $PATH 环境变量中包含的目录下进行查找。因此，只要我们将一个可执行文件放入了 $PATH 中的目录下面，我们就可以像 `apt` 一样，在任意地方调用我们的程序。 | ||
| 在这里我们需要知道什么是 `PATH` 变量，当我们在终端输入命令时，终端会先判断是否为终端的内建命令，如果不是，则会在 `$PATH` 环境变量中包含的目录下进行查找。因此，只要我们将一个可执行文件放入了 `$PATH` 中的目录下面，我们就可以像 `apt` 一样，在任意地方调用我们的程序。 |
docs/Ch03/index.md
Outdated
| $ sudo mkdir /usr/local/clang-10.0.0 | ||
| $ # 将 clang+llvm-10.0.0-x86_64-linux-gnu-ubuntu-18.04 整个目录复制到新建的 /usr/local/clang-10.0.0 下。 | ||
| $ sudo cp -R * /usr/local/clang-10.0.0 | ||
| $ echo 'export PATH=/usr/local/clang-10.0.0/bin:$PATH' >> ~/.bashrc |
docs/Ch03/index.md
Outdated
| $ source ~/.bashrc | ||
| ``` | ||
|
|
||
| 这两条命令将当前 `clang-10.0.0` 目录添加到 PATH 环境变量中。 |
另外请不要用 AI 生成这么长一段英文描述：没人会看。真的要概括的话，一两句中文就够了。 |
Co-authored-by: taoky <[email protected]>
Co-authored-by: taoky <[email protected]>
Co-authored-by: taoky <[email protected]>
针对之前提交的 pr 对修改内容进行了格式编辑已经 llvm 的版本升级，并修改了关于 apt 的啰嗦内容
2 participants
Description
What this PR does
This PR revises the Clang installation instructions to adopt a safer and more maintainable approach.
The documentation now recommends installing Clang into a versioned directory under /usr/local/ (e.g. /usr/local/clang-10.0.0), rather than copying binaries directly into system paths.
Key updates include:
• Clarified the purpose and proper usage of the $PATH environment variable.
• Replaced unsafe guidance involving copying files into /usr/local/bin and /usr/local/lib.
• Added instructions for setting up a dedicated versioned installation directory.
• Improved clarity, accuracy, and long-term maintainability of the document.
Why this change is needed
Copying Clang’s binaries and libraries directly into system directories can:
• pollute system paths
• overwrite existing files
• break version management
• make the installation hard to roll back
Using a versioned directory under /usr/local/ is a widely accepted best practice for managing external binary distributions. It avoids conflicts and allows multiple versions of Clang to coexist cleanly.
How it was tested
• Verified that Clang runs correctly from /usr/local/clang-10.0.0/bin.
• Confirmed PATH modifications behave as expected.
• Ensured that no existing system files are modified or overwritten.
Impact
This PR affects only documentation.
No functional or behavioral changes to the software itself.
Additional notes
If future versions of Clang are added, they can follow the same directory structure without interfering with existing installations.