文档【免费下载链接】rfcsRFCs for changes to Rust项目地址https://gitcode.com/gh_mirrors/rf/rfcs点击查看免费下载本篇文章以 Rust RFC 仓库中的 RFC 2951 原文 为核心系统讲解#[link]属性与-l命令行选项新增的modifiers机制如何通过whole-archive、verbatim、bundle、as-needed四个修饰符精细控制原生库的链接行为覆盖语法规则、各修饰符的兼容性与链接器翻译、稳定化策略以及与 RFC 1717dllimport、RFC 2627raw-dylib 的演进关系。读完本文你将掌握在 Rust 中整包链接静态库、按原样传递库名、按需链接动态库的完整写法并能看懂 rustc 链接命令行背后的语义。RFC 背景为什么需要链接修饰符在 Rust 中链接原生native库时偶尔需要对链接行为做一些细粒度的调整但长期以来缺少对应的机制。RFC 2951 提出了三类典型诉求整包链接静态库有些静态库中的符号表面上未被使用实际上却有副作用如注册表初始化、构造器函数。默认链接时链接器会丢弃看起来用不到的目标文件object file因此需要一种方式要求把整个归档全部链接进来。RFC 用whole-archive修饰符解决。按原样传递库名有些库位于特定路径、或者不符合默认命名约定如lib前缀、.a后缀直接按名字搜索可能失败。RFC 用verbatim修饰符解决。拆分链接 kindstatic-nobundle这种链接 kind 语义混杂RFC 将其重构为bundle修饰符为将来在某个 edition 边界改变静态链接的默认行为留下余地并有望解除其稳定化阻塞。更关键的是这套通用语法为未来增加更多修饰符提供了通道——不必再为每种链接行为引入新的链接 kind只需追加一个修饰符即可。既有语法回顾#[link]属性与-l命令行在扩展之前Rust 已有的原生库链接语法如下属性形式#[link(name string, kind string, cfg(predicate))]其中部分组件是可选的。命令行形式-l kindname:rename部分组件同样可选。其中命令行-l的kindname:rename三段式语法KIND可覆盖源码中声明的链接 kind、NEWNAME可覆盖库名源自 RFC 1717dllimport 的Library name and kind variance一节用于支撑构建脚本对同名库在不同平台/发行版上名称与链接方式可能不同这一动态性的处理。扩展后的语法modifiers的写法与语义RFC 2951 在保持既有语法不变的基础上做了两处对等扩展属性形式#[link(/* 原有组件 */, modifiers foo,-bar)]命令行形式-l kind:foo,-barname:rename修饰符是布尔型的且只作用于name指定的那一个库表示启用-表示禁用多个修饰符用逗号分隔同一个修饰符被多次指定时最后一个布尔值生效后面的覆盖前面的。这套记号整体借用了 rustc 的target-feature语法见 rustc 代码生成选项文档语义与之保持一致。例如下面的写法意思是启用whole-archive、禁用bundle#[link(name mylib, kind static, modifiers whole-archive,-bundle)] extern C { fn mylib_init(); }命令行上若同时指定了:rename组件那么除了库名与链接 kind 会被更新外修饰符也会一并更新按拼接方式累加# 原声明 #[link(name foo, kind static, modifiers whole-archive)] # 命令行追加 -bundle最终效果为 whole-archive,-bundle且链接 bar 而不是 foo rustc main.rs -l static:-bundlefoo:bar四个具体修饰符详解RFC 2951 一次性定义了四个修饰符各自有严格的链接 kind 兼容性与链接器翻译规则。下表先做总览随后逐项展开修饰符兼容的链接 kind默认值典型链接器翻译bundlestatic当前bundle未来 edition 可能改变rustc 自身行为不翻译给链接器verbatim通用与raw-dylib结合使用-verbatimld类用-l:filename不支持的链接器原样传名whole-archivestatic-whole-archiveld--whole-archivelink.exe/WHOLEARCHIVEld64-force_loadas-neededdynamic、framework各目标不一致待统一ld--as-neededld64-dead_strip_dylibs/-needed_library/-needed_frameworkbundle打包进 crate 还是交给最终链接bundle只兼容static链接 kind描述静态库对象文件的归属时机bundle静态库中的对象文件被打包进当前产出的 crate例如 rlib后续最终二进制链接时直接从该 crate 中取出使用。-bundle静态库以按名字引用的方式被包含进 rlib对象文件只有在最终二进制链接时才真正纳入对库名的文件搜索同样推迟到最终链接阶段执行。这一修饰符被设计为取代 RFC 1717 中定义的static-nobundle链接 kind不打包进 rlib、但链接方式同 static即把一种链接 kind重构成一种修饰符组合。当前默认值是bundle但 RFC 明确预留了在未来某个 edition 边界将静态链接默认改为非打包-bundle的可能性——这正是拆分 kind 的核心动机之一。verbatim按原样传递库名verbatim控制库名在传给链接器之前是否被 rustc 加工verbatimrustc 自己不再添加目标平台约定的前缀或后缀如lib前缀、.a后缀并尽力要求链接器也照做。对于ld类链接器rustc 使用-l:filename语法注意冒号传递库名链接器因此不会再加任何前缀后缀——这正是ld文档中-l namespec的语义对于不支持任何 verbatim 形式的链接器如link.exe或ld64库名会原样传递。默认值为-verbatim。verbatim的典型场景是链接名字不符合默认约定的库。例如一个实际文件名是mystuff-v2.a的静态库可以写成#[link(name mystuff-v2.a, kind static, modifiers verbatim)] extern C { fn stuff(); }verbatim与raw-dylib的行为变化RFC 2951 同时改变了 RFC 2627 定义的raw-dylib链接 kind 的行为现在.dll后缀或该目标上其他目标指定的后缀会被自动添加不再要求用户在name中显式写出扩展名。如果你的 DLL 确实不带.dll后缀则用verbatim明确指定即可// 自动补全为 mydll.dll #[link(name mydll, kind raw-dylib)] extern system { fn myfunc(); } // 库文件不带 .dll 后缀按原样传递 #[link(name mydll_nosuffix, kind raw-dylib, modifiers verbatim)] extern system { fn myfunc2(); }这一改动让raw-dylib的使用与普通dylib的习惯对齐通常只需写库名核心部分同时保留了非常规命名的逃生通道。whole-archive整包链接静态库whole-archive只兼容static链接 kindwhole-archive静态库作为整个归档archive链接不会丢弃任何对象文件——即使某些符号看起来未被引用。链接器翻译ld类链接器用--whole-archivelink.exe用/WHOLEARCHIVEld64用-force_load对不支持的链接器该修饰符不产生任何效果。默认值为-whole-archive。这正是库内符号有副作用、不能被死代码剥离场景的解法RFC 给出的动机示例来自 rustc 的 issue #56306。典型写法#[link(name side_effect_lib, kind static, modifiers whole-archive)] extern C { fn register_things(); }as-needed按需链接动态库与框架as-needed只兼容dynamic与framework两种链接 kindas-needed库仅在满足命令行当前位置尚未解析的未定义符号时才被真正链接行为上接近静态库的按需特性从而避免无谓地把动态库拉进依赖。链接器翻译ld类链接器用--as-neededld64用-dead_strip_dylibs/-needed_library/-needed_framework对不支持它的链接器如link.exe不产生任何效果。默认值在 RFC 阶段尚不明确部分目标当前就默认as-needed部分则没有RFC 提出可以尝试让所有目标统一默认as-needed。使用时建议显式声明不要依赖跨目标一致的默认值。RFC 给出的动机示例来自 rustc 的 issue #57837。典型写法#[link(name optional_dep, kind dynamic, modifiers as-needed)] extern C { fn maybe_used(); }稳定性策略语法与具体修饰符解耦RFC 对稳定化路径做了刻意设计修饰符语法本身可以独立于任何具体修饰符先行稳定——即modifiers foo,-bar的解析与表示机制每个具体修饰符则从不稳定状态开始且可以彼此独立地在需求足够时逐个稳定化。这意味着whole-archive与as-needed不必捆绑推进bundle对static-nobundle的替代也不必等待verbatim就绪演进粒度更细。顺序保证-l与-Clink-arg(s)的相对顺序RFC 2951 还提出一项对命令行语义的重要保证rustc的-l与-Clink-arg(s)选项在传给链接器时必须保持原有的相对顺序当前实现是分别独立传递顺序不受保证。这一保证的价值在于用户可以在命令行上用原始链接器选项精确干预单个库的链接。典型组合是围绕-l前后分别放置开启与关闭选项# 用原始链接器选项实现类似 whole-archive 的效果 rustc main.rs -Clink-arg-Wl,--whole-archive -l foo -Clink-arg-Wl,--no-whole-archive注意上例中的-Wl,前缀只在以gcc作为链接驱动时必要若直接调用ld类链接器则不需要。RFC 同时说明目前不提供保持顺序的-Clink-arg的属性形式等价物。设计权衡与备选方案RFC 明确列出了两种主要备选方案及其被否定的理由。备选一完全依赖原始链接器选项把相对跨平台的whole-archive与as-needed效果完全交给目标特定的原始链接器选项即上文-Clink-arg-Wl,--whole-archive那种写法。RFC 指出该方案的缺陷它不仅目标特定还链接器特定gcc驱动需要-Wl,直接ld不需要-Wl,前缀理论上可以由工具自动补全——CMake 的target_link_options命令中的LINKER:修饰符已有相关先例若要沿用属性形式实现则需要引入全新的属性对应Future possibilities中的#[link(arg string)]更关键的是原始链接器选项完全覆盖不了bundle与verbatim——这两个是 rustc 自身语义与具体链接器无关。备选二把修饰符合并进kind将写法改成#[link(kind static:foo,-bar)]让属性更贴近命令行命令行本来就是kindname的拼写。RFC 的结论是虽然这会让属性与命令行更一致但是否值得追求这种一致性本身并不明确——毕竟命令行写kindname而属性中kind与name本来就是两个独立字段kind ..., name ...两种媒介的语法差异是既有事实。先例参考gcc与cl.exegcc提供-Wl,foo语法及其他类似选项向链接器直传任意选项且-Wl选项与-l选项的相对顺序被保留——这是顺序保证提议的直接参照物。cl.exe提供/link link-opts直传链接器选项但link.exe的选项普遍顺序无关因此对针对特定库调整行为这一目标远不如ld类链接器相关。未决问题与未来方向RFC 的 Unresolved questions 一节当前为空None currently.。但 Future possibilities 提出了两个明确方向dedup修饰符为库去重预留开关rustc 当前并不对链接库做通用去重原因是某些罕见情况下同一库确实需要在命令行上重复出现。这类情况很少因此未来可能把默认去重作为目标同时提供-dedup修饰符作为少数需要重复场景的退出开关。RFC 特别指出在当前-dedup不去重已是默认的前提下立刻引入dedup修饰符意义不大——它真正的价值在于配合默认去重的转变。#[link(arg string)]属性形式的顺序保留链接参数ld还支持一些冷门的按库选项如--copy-dt-needed-entries以及顺序依赖的组选项如--start-group/--end-group作用于一组库。与其为每个这类场景发明新修饰符不如提供一个顺序保留的、属性形式的-C link-arg等价物。这一能力还可能顺带解决长期存在的 unstable 属性#[link_args]的问题并作为它的替代品结合前面提到的 CMakeLINKER:思路可以进一步提升可移植性。实践建议什么时候用哪个修饰符综合全文给出按场景选型的速查静态库内有副作用符号、必须整包链接kind static, modifiers whole-archive静态库不应被打包进 rlib、留到最终链接按名搜索modifiers -bundle替代旧static-nobundlekind库文件名不符合lib/.a约定或 DLL 不带.dll后缀modifiers verbatim与raw-dylib组合时尤其常见动态库/框架仅在满足符号时才应被链接kind dynamic/framework, modifiers as-needed注意其默认值跨目标不一致务必显式声明需要在命令行精确控制单个库的链接依赖 RFC 保证的-l与-Clink-arg(s)相对顺序在其前后穿插原始链接器选项。需要注意的是bundle、verbatim、whole-archive与as-needed均属于高级特性RFC 的 Guide-level explanation 明确说明这不是预期会被普遍使用的特性——只有确认需要时才使用。所有具体修饰符在 RFC 中均以 unstable 起步使用前应结合所使用 rustc 版本的 feature gate 与稳定化状态确认可用性本仓库内可继续查阅 RFC 2951 原文、RFC 1717dllimportstatic-nobundle与-l kindname:rename的来源 以及 RFC 2627raw-dylib kind 获取完整设计细节。赞分享文档【免费下载链接】rfcsRFCs for changes to Rust项目地址https://gitcode.com/gh_mirrors/rf/rfcs点击查看免费下载相关推荐Rust RFC 403 深度解读Cargo build 命令重构与 *-sys 原生链接体系Rust RFC 403 深度解读Cargo build 命令重构与 sys 原生链接体系 导读 本文深度解读 Rust RFC 403 原始文档 http文档Sunshine 串流主机搭建3 步跑通 Moonlight 游戏串流只需 1 条安装命令Sunshine 串流主机搭建3 步跑通 Moonlight 游戏串流只需 1 条安装命令 Sunshine 是自托管游戏串流服务器配 Moonlight音视频后端Imba 事件修饰符Event Modifiers完全指南内置修饰符、自定义修饰符与处理链机制Imba 事件修饰符Event Modifiers完全指南内置修饰符、自定义修饰符与处理链机制 事件修饰符Event Modifiers是 Imba编程语言编译器语言运行时上一篇碧蓝航线自动化助手智能解放你的游戏时间下一篇OpenRig office-hours 技能用六个强制问题完成 YC 式产品验证产出 GO/REFINE/PAUSE 裁决创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考