[PATCH] docs/zh_CN: add the translation of kbuild/gcc-plugins.rst

[Dongliang Mu]

Finish the translation of kbuild/gcc-plugins.rst and move gcc-plugins
from TODO to the main body.

Update to commit 3832d1fd84b6 ("docs/core-api: expand Fedora instructions
for GCC plugins")

Signed-off-by: Dongliang Mu <dz...@hust.edu.cn>
---
.../translations/zh_CN/kbuild/gcc-plugins.rst | 126 ++++++++++++++++++
.../translations/zh_CN/kbuild/index.rst | 2 +-
2 files changed, 127 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_CN/kbuild/gcc-plugins.rst

diff --git a/Documentation/translations/zh_CN/kbuild/gcc-plugins.rst b/Documentation/translations/zh_CN/kbuild/gcc-plugins.rst
new file mode 100644
index 000000000000..214945a4ecf3
--- /dev/null
+++ b/Documentation/translations/zh_CN/kbuild/gcc-plugins.rst
@@ -0,0 +1,126 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/kbuild/gcc-plugins.rst
+:Translator: 慕冬亮 Dongliang Mu <dz...@hust.edu.cn>
+
+================
+GCC 插件基础设施
+================
+
+
+介绍
+============
+
+GCC 插件是为编译器提供额外功能的可加载模块 [1]_。它们对于运行时插装和静态分析非常有用。
+我们可以在编译过程中通过回调 [2]_，GIMPLE [3]_，IPA [4]_ 和 RTL Passes [5]_
+（译者注：Pass 是编译器所采用的一种结构化技术，用于完成编译对象的分析、优化或转换等功能）
+来分析、修改和添加更多的代码。
+
+内核的 GCC 插件基础设施支持构建树外模块、交叉编译和在单独的目录中构建。插件源文件必须由
+C++ 编译器编译。
+
+目前 GCC 插件基础设施只支持一些架构。搜索 "select HAVE_GCC_PLUGINS" 来查找支持
+GCC 插件的架构。
+
+这个基础设施是从 grsecurity [6]_ 和 PaX [7]_ 移植过来的。
+
+--
+
+.. [1] https://gcc.gnu.org/onlinedocs/gccint/Plugins.html
+.. [2] https://gcc.gnu.org/onlinedocs/gccint/Plugin-API.html#Plugin-API
+.. [3] https://gcc.gnu.org/onlinedocs/gccint/GIMPLE.html
+.. [4] https://gcc.gnu.org/onlinedocs/gccint/IPA.html
+.. [5] https://gcc.gnu.org/onlinedocs/gccint/RTL.html
+.. [6] https://grsecurity.net/
+.. [7] https://pax.grsecurity.net/
+
+
+目的
+=======
+
+GCC 插件的设计目的是提供一个场所，用于试验 GCC 或 Clang 上游没有的潜在编译器功能。
+一旦它们的实用性得到验证，目标就是将这些功能添加到 GCC（和 Clang）的上游，然后在
+所有支持的 GCC 版本都支持这些功能后，再将它们从内核中移除。
+
+具体来说，新插件应该只实现上游编译器（GCC 和 Clang）不支持的功能。
+
+当 Clang 中存在 GCC 中不存在的某项功能时，应努力将该功能上传到上游 GCC（而不仅仅
+是作为内核专用的 GCC 插件），以使整个生态都能从中受益。
+
+类似的，如果 GCC 插件提供的功能在 Clang 中 **不** 存在，但该功能被证明是有用的，也应
+努力将该功能上传到 GCC（和 Clang）。
+
+在上游 GCC 提供了某项功能后，该插件将无法在相应的 GCC 版本（以及更高版本）下编译。
+一旦所有内核支持的 GCC 版本都提供了该功能，该插件将从内核中移除。
+
+
+文件
+=====
+
+**$(src)/scripts/gcc-plugins**
+
+ 这是 GCC 插件的目录。
+
+**$(src)/scripts/gcc-plugins/gcc-common.h**
+
+ 这是 GCC 插件的兼容性头文件。
+ 应始终包含它，而不是单独的 GCC 头文件。
+
+**$(src)/scripts/gcc-plugins/gcc-generate-gimple-pass.h,
+$(src)/scripts/gcc-plugins/gcc-generate-ipa-pass.h,
+$(src)/scripts/gcc-plugins/gcc-generate-simple_ipa-pass.h,
+$(src)/scripts/gcc-plugins/gcc-generate-rtl-pass.h**
+
+ 这些头文件可以自动生成 GIMPLE、SIMPLE_IPA、IPA 和 RTL passes 的注册结构。
+ 与手动创建结构相比，它们更受欢迎。
+
+
+用法
+=====
+
+你必须为你的 GCC 版本安装 GCC 插件头文件，以 Ubuntu 上的 gcc-10 为例::
+
+ apt-get install gcc-10-plugin-dev
+
+或者在 Fedora 上::
+
+ dnf install gcc-plugin-devel libmpc-devel
+
+或者在 Fedora 上使用包含插件的交叉编译器时::
+
+ dnf install libmpc-devel
+
+在内核配置中启用 GCC 插件基础设施与一些你想使用的插件::
+
+ CONFIG_GCC_PLUGINS=y
+ CONFIG_GCC_PLUGIN_LATENT_ENTROPY=y
+ ...
+
+运行 gcc（本地或交叉编译器），确保能够检测到插件头文件::
+
+ gcc -print-file-name=plugin
+ CROSS_COMPILE=arm-linux-gnu- ${CROSS_COMPILE}gcc -print-file-name=plugin
+
+"plugin" 这个词意味着它们没有被检测到::
+
+ plugin
+
+完整的路径则表示插件已经被检测到::
+
+ /usr/lib/gcc/x86_64-redhat-linux/12/plugin
+
+编译包括插件在内的最小工具集::
+
+ make scripts
+
+或者直接在内核中运行 make，使用循环复杂性 GCC 插件编译整个内核。
+
+
+4. 如何添加新的 GCC 插件
+==============================
+
+GCC 插件位于 scripts/gcc-plugins/。你需要将插件源文件放在 scripts/gcc-plugins/ 目录下。
+子目录创建并不支持，你必须添加在 scripts/gcc-plugins/Makefile、scripts/Makefile.gcc-plugins
+和相关的 Kconfig 文件中。
diff --git a/Documentation/translations/zh_CN/kbuild/index.rst b/Documentation/translations/zh_CN/kbuild/index.rst
index d906a4e88d0f..b51655d981f6 100644
--- a/Documentation/translations/zh_CN/kbuild/index.rst
+++ b/Documentation/translations/zh_CN/kbuild/index.rst
@@ -13,6 +13,7 @@
:maxdepth: 1

headers_install
+ gcc-plugins

TODO:

@@ -24,7 +25,6 @@ TODO:
- modules
- issues
- reproducible-builds
-- gcc-plugins
- llvm

.. only:: subproject and html
--
2.43.0

[YanTeng Si]

Please trim the length of the equal sign line.

I will continue reviewing later or tomorrow.


Thank,
Yanteng

[YanTeng Si]

How about:
GCC 插件的设计目的是提供一个用于试验 GCC 或 Clang
上游没有的潜在编译器功能的场所。

>>
>> +一旦它们的实用性得到验证，目标就是将这些功能添加到 GCC（和
>> Clang）的上游，然后在
>> +所有支持的 GCC 版本都支持这些功能后，再将它们从内核中移除。

目标是 进上游后 把 功能 移除。
Can we re-polish it here?

>> +
>> +具体来说，新插件应该只实现上游编译器（GCC 和 Clang）不支持的功能。
>> +
>> +当 Clang 中存在 GCC 中不存在的某项功能时，应努力将该功能上传到上游
>> GCC（而不仅仅

应努力将该功能做到 GCC上游

Thanks,
Yanteng
>
>

[Dongliang Mu]

一旦它们的实用性得到验证，这些功能将被添加到 GCC（和 Clang）的上游。
随后，在所有支持的 GCC 版本都支持这些功能后，它们会被从内核中移除。
How about this?

[YanTeng Si]

在 2024/8/30 16:17, Dongliang Mu 写道:
>>>> +一旦它们的实用性得到验证，目标就是将这些功能添加到 GCC（和
>>>> Clang）的上游，然后在
>>>> +所有支持的 GCC 版本都支持这些功能后，再将它们从内核中移除。
>> 目标是 进上游后 把 功能 移除。
>> Can we re-polish it here?
> 一旦它们的实用性得到验证，这些功能将被添加到 GCC（和 Clang）的上游。
> 随后，在所有支持的 GCC 版本都支持这些功能后，它们会被从内核中移除。
> How about this?

Great!

Thanks,
Yanteng

[Dongliang Mu]

Finish the translation of kbuild/gcc-plugins.rst and move gcc-plugins
from TODO to the main body.

Update to commit 3832d1fd84b6 ("docs/core-api: expand Fedora instructions
for GCC plugins")

Signed-off-by: Dongliang Mu <dz...@hust.edu.cn>
---

v1->v2: fix comments from yanteng

.../translations/zh_CN/kbuild/gcc-plugins.rst | 126 ++++++++++++++++++
.../translations/zh_CN/kbuild/index.rst | 2 +-
2 files changed, 127 insertions(+), 1 deletion(-)
create mode 100644 Documentation/translations/zh_CN/kbuild/gcc-plugins.rst

diff --git a/Documentation/translations/zh_CN/kbuild/gcc-plugins.rst b/Documentation/translations/zh_CN/kbuild/gcc-plugins.rst
new file mode 100644

index 000000000000..f31fed139289

--- /dev/null
+++ b/Documentation/translations/zh_CN/kbuild/gcc-plugins.rst
@@ -0,0 +1,126 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. include:: ../disclaimer-zh_CN.rst
+
+:Original: Documentation/kbuild/gcc-plugins.rst
+:Translator: 慕冬亮 Dongliang Mu <dz...@hust.edu.cn>
+
+================
+GCC 插件基础设施
+================
+
+
+介绍
+=====

+
+GCC 插件的设计目的是提供一个用于试验 GCC 或 Clang 上游没有的潜在编译器功能的场所。
+一旦它们的实用性得到验证，这些功能将被添加到 GCC（和 Clang）的上游。随后，在所有
+支持的 GCC 版本都支持这些功能后，它们会被从内核中移除。

+
+具体来说，新插件应该只实现上游编译器（GCC 和 Clang）不支持的功能。
+

+当 Clang 中存在 GCC 中不存在的某项功能时，应努力将该功能做到 GCC 上游（而不仅仅

--
2.43.0

[Alex Shi]

On 8/31/24 11:48 AM, Dongliang Mu wrote:
> +目的
> +=======
> +

there are still a lots of sign incorrect. Please be sure everything looks fine in a web browser after you 'make htmldocs'

Thanks

[Dongliang Mu]

What do you mean by "sign incorrect"? I check the html rendering in the
vscode. It seems fine to me.

Dongliang Mu

>
> Thanks
>

[Akira Yokosawa]

Hi,

I'm not Alex, but let me chime in.

You are right. There is nothing wrong as far as the reST specification
is concerned.

Quote from https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#sections
(emphasis by me):

An underline/overline is a single repeated punctuation character that
begins in column 1 and forms a line extending *at least* as far as the
right edge of the title text.

HTH, Akira

>
> Dongliang Mu

[Dongliang Mu]

I see. Will send a v3 patch.

> HTH, Akira
>
> >
> > Dongliang Mu
>
>

[YanTeng Si]

Yes, I guess we should also think about the reading experience
of readers who use vim to read kernel documentation.

Because Chinese characters are already very neat, sentences
and paragraphs should also be neat, otherwise the reading
experience will be poor.

Let's take a look at some examples: (copy to vim)

整齐
====
整齐
====
整齐
====
Great!


And


不整齐
============
不整齐
=========
不整齐
================
I think this is a bit difficult to read. What do you think?



Thanks,
Yanteng
> HTH, Akira
>
>> Dongliang Mu
>

[Akira Yokosawa]

On Mon, 2 Sep 2024 09:32:08 +0800, YanTeng Si wrote:
...

So you are talking about your personal preference, not about what is
technically correct or wrong.
And you are exaggerating by collecting them in one place.

If they appeared springily as title adornments, they would not bother
me at all.

At times, especially with a very short title, I'd like to have a way
longer adornment line to make it stand out such as:

整齐
------------

Of course I don't have a say on personal preferences and I think
maybe I was stupid making a *technical* comment here in the first
place. :-/

Akira.

[YanTeng Si]

Hi Akira,

In a sense, yes.

> And you are exaggerating by collecting them in one place.
>
> If they appeared springily as title adornments, they would not bother
> me at all.

Sorry, my example is not good enough.

>
> At times, especially with a very short title, I'd like to have a way
> longer adornment line to make it stand out such as:
>
> 整齐
> ------------

Okay, I'm not a stubborn person, I just care about the feelings of most
people.

If you open any document, you will find that the author is trying to keep
everything as neat as possible.

let's vim kbuild/gcc-plugins.rst

---

=========================
GCC plugin infrastructure
=========================


Introduction
============

GCC plugins are loadable modules that provide extra features to the
compiler [1]_. They are useful for runtime instrumentation and static
analysis.
We can analyse, change and add further code during compilation via
callbacks [2]_, GIMPLE [3]_, IPA [4]_ and RTL passes [5]_.

...


Purpose
=======

GCC plugins are designed to provide a place to experiment with potential
compiler features that are neither in GCC nor Clang upstream. Once
their utility is proven, the goal is to upstream the feature into GCC
(and Clang), and then to finally remove them from the kernel once the
feature is available in all supported versions of GCC.

...

After a feature is available in upstream GCC, the plugin will be made
unbuildable for the corresponding GCC version (and later). Once all
kernel-supported versions of GCC provide the feature, the plugin will
be removed from the kernel.


Files
=====

**$(src)/scripts/gcc-plugins**

....
    These headers automatically generate the registration structures for
    GIMPLE, SIMPLE_IPA, IPA and RTL passes.
    They should be preferred to creating the structures by hand.


Usage
=====

You must install the gcc plugin headers for your gcc version,
e.g., on Ubuntu for gcc-10::

.....

or just run the kernel make and compile the whole kernel with
the cyclomatic complexity GCC plugin.


4. How to add a new GCC plugin
==============================

The GCC plugins are in scripts/gcc-plugins/. You need to put plugin
source files
right under scripts/gcc-plugins/. Creating subdirectories is not supported.
It must be added to scripts/gcc-plugins/Makefile,
scripts/Makefile.gcc-plugins
and a relevant Kconfig file.

---

We can see that all the underline are aligned with the title,  Even each
row is
as long as possible. I think most readers are also accustomed to alignment.


In addition, we are only translating from English to Chinese, and the
translation should be as consistent as possible with the original
document to facilitate readers/developers to compare the original
document. Because our translations may not be accurate and updates
may not be timely, keeping them consistent with English will make
everything simpler.

>
> Of course I don't have a say on personal preferences and I think
> maybe I was stupid making a *technical* comment here in the first
> place. :-/

Don't say that, your comment makes this matter clearer and greatly
reduces the difficulty of discussion. I understand your feelings very
well, as I replied to your first comment by saying 'yes', and then I
elaborated on my point of view, although not entirely perfect.


Thanks,
Yanteng

[Alex Shi]

vscode isn't good to show the correctness of the doc. Please try the thing reviewer pointed out.

Thanks

>
> Dongliang Mu
>
>>
>> Thanks
>>  
>