科研科学计算高性能计算【免费下载链接】lammpsPublic development project of the LAMMPS MD software package项目地址https://gitcode.com/gh_mirrors/la/lammps点击查看免费下载导读本文以 doc/src/Build_manual.rst 为骨架系统讲解 LAMMPS 官方手册HTML / PDF / ePUB / MOBI的完整构建流程先厘清doc目录的文件布局再分别介绍基于 GNU make 与 CMake 的两种构建方式随后给出各输出格式的前置依赖清单最后面向文档贡献者说明快速预览、一致性检查与拼写检查等开发期工具链。读完本文你将掌握从 git 源码自行生成 LAMMPS 手册、把 HTML 手册并入 CMake 安装流程以及为新增 style 编写并验证文档的完整技能。一、先认识doc目录一份手册多种形态LAMMPS 的文档体系集中在一个doc目录中但其中既有源文件也有构建产物还有构建工具。是否齐全取决于你获取 LAMMPS 的方式从官网下载的 tarball 压缩包通常已经预置html目录HTML 版手册入口是html/Manual.html和 PDF 文件开箱即用从 git 仓库克隆HTML、PDF 等产物不在仓库内需要自行构建。doc目录下的文件与子目录职责如下条目说明README关于本目录的简要说明doc/READMEsrc手册的 reStructuredText 内容源文件约千余个.rst如 doc/src/Manual.rsthtmlHTML 版手册构建产物入口html/Manual.htmlutils文档构建所需的工具与配置lammps.1/msi2lmp.1两个命令的 man pageManual.pdf/LAMMPS.epub/LAMMPS.mobi三种电子出版物格式的完整手册docenv存放文档构建用 Python 虚拟环境的目录doctreesSphinx 构建产生的中间数据doxygenDoxygen 配置与输出.gitignoregit 忽略规则doxygen-warn.log运行 Doxygen 时产生的警告日志github-development-workflow.mdLAMMPS 开发工作流备忘在仓库当前状态中doc顶层只保留了源文件与构建工具src、utils、doxygen、graphviz等html、Manual.pdf等产物目录需要你自己构建才会生成——这与 git 克隆方式的预期完全一致。二、构建工具链全景RST Sphinx Doxygen MathJaxLAMMPS 手册采用reStructuredTextRST撰写借助Sphinx文档生成器转换为多种输出格式同时通过Doxygen从 LAMMPS C 源码中抽取程序员文档Programmers Guide并合入手册。整套流水线中每个环节的职责RST 源文件doc/src全部手册页面的内容载体Sphinx负责将 RST 翻译为 HTML、PDF经 LaTeX、ePUBDoxygen从 src 的 C 源码生成 XML再经 breathe 等扩展嵌入手册形成面向开发者的 API 文档——其配置见 doc/doxygen/Doxyfile.in工程名即LAMMPS Programmers GuideMathJax在 HTML 输出中渲染嵌入的 LaTeX 数学表达式Pandoc仅用于开发期的快速近似 HTML 预览make fasthtml。构建时会在doc/docenv下创建 Python 虚拟环境并通过 pip 安装依赖。依赖清单集中在 doc/utils/requirements.txt包括Sphinx 6, 9.2.0、sphinxcontrib-spelling、sphinx-design、sphinx-sitemap、sphinx-tabs3.4.1、breathe、Pygments、docutils 0.18, 0.23等。从 doc/Makefile 可以看到关键实现细节虚拟环境路径固定为docenvVENV $(BUILDDIR)/docenvSphinx 配置conf.py由utils/sphinx-config/conf.py.in模板经 sed 替换变量生成其中会注入src源码目录、python模块目录等路径MathJax 通过git clone拉取固定 tagMATHJAXTAG 4.1.3正式构建前会先执行xmlgen运行 Doxygen 生成doxygen/xml/index.xml与globbed-tocs生成手册目录再调用sphinx-build -E -b html -c ...。需要说明的是首次构建必须有网络访问用于下载 MathJax 等外部资源之后除非执行make clean-all重置一般无需重复下载。三、GNU make 构建目标命令全解在doc目录下执行make即可构建。以下命令均以doc目录为工作目录3.1 四种正式输出格式make html # 用 Sphinx 生成 HTML输出到 html 目录 make pdf # 用 Sphinx PDFLaTeX 生成 Manual.pdf make epub # 用 Sphinx 生成 LAMMPS.epubePUB 电子书格式 make mobi # 用 ebook-convert 将 ePUB 转换为 LAMMPS.mobiMOBI 格式make mobi会先构建 ePUB 再执行格式转换因此依赖 5.3 节 提到的 calibreebook-convert工具。3.2 开发期快速预览make fasthtml完整翻译整个手册耗时较长因此提供了基于Pandoc的“快而糙”的 HTML 预览通道用于编写/修改单个页面时快速检查语法与排版make fasthtml # 翻译全部 .rst输出到 fasthtml 目录 make -j 4 fasthtml # 支持 make 的 -j 并行加速 make fasthtml/pair_lj.html # 只翻译单页例如 doc/src/pair_lj.rst注意Pandoc 不识别 Sphinx 的专属特性交叉引用、高级表格、Python docstring 嵌入、Doxygen 文档等这些内容在 fasthtml 中不会正确渲染但大部分嵌入的数学公式可以正常显示。从 doc/Makefile 的fasthtml/%.html规则可见它实际是sed处理特殊符号后直接调用pandoc -s --mathml --csspandoc.css。该通道仅用于开发预览最终仍须用make html与make pdf验证正式输出。3.3 环境维护命令make upgrade # 升级 docenv 中的 sphinx、扩展及依赖到最新受支持版本 make clean # 移除 HTML 构建产生的中间 RST 文件与缓存 make clean-all # 完全重置删除整个构建目录与全部缓存含 docenv、MathJaxmake clean-all会删除docenv、MathJax、Manual.pdf、LAMMPS.epub、LAMMPS.mobi及所有中间目录让文档目录回到“首次构建”的初始状态。3.4 质量检查make check 系列make check # 依次运行下方所有检查 make anchor_check # 检查重复的 anchor 标签 make style_check # 检查 style 列表是否完整一致 make package_check # 检查包列表是否完整一致 make char_check # 检查非 ASCII 字符 make role_check # 检查格式错误的 role 关键字 make example_check # 检查指向 examples 的链接是否失效或缺失 make link_check # 检查外部 URL 是否失效 make spelling # 对整本手册做拼写检查从 doc/Makefile 的help目标中还可以看到额外的extract_check检查 extract() 函数与手册表格的一致性。这些检查大多有对应的独立脚本位于 doc/utils例如rst_anchor_check.py、check-packages.py、check-styles.py、find_example_refs.py其逻辑会在 第六节 展开。四、CMake 构建把 HTML 手册并入安装流程除了在doc目录用 make 构建还可以在CMake 构建目录中生成 HTML 版手册仅 HTML。这样做的意义在于可以把 HTML 手册的安装并入cmake --build . --target install的安装步骤。配置开关-D BUILD_DOCvalue # yes 或 no默认行为细节依据 cmake/Modules/Documentation.cmake 的实现BUILD_DOC默认关闭开启后还会引出BUILD_DOC_VENV默认 ON选项控制是否为文档构建创建虚拟环境要求 Python ≥ 3.8低于此版本会FATAL_ERROR并要求Doxygen ≥ 1.8.10文档构建默认包含在默认 build target 中也可独立触发cmake --build . --target doc构建完成后install(DIRECTORY ... html ...)会把 HTML 手册安装到系统文档目录这正是 doc/src/Build_cmake.rst 中 CMake 流程的一部分与 make 流程一致可通过PIP_OPTIONS环境变量向 pip 传递额外选项如代理或额外 SSL 证书配置与静态文件会被复制到二进制目录doc下以避免并行构建时的冲突。两条构建通道各有适用场景make 方式功能最全HTML/PDF/ePUB/MOBI 全套检查CMake 方式则适合希望“构建 LAMMPS 本体时顺带生成并安装 HTML 手册”的用户。五、前置依赖准备5.1 HTML 构建依赖构建 HTML 手册需要本地安装Python 3.8 或更高版本、git、doxygen、virtualenvvenv 模块外加首次构建的网络访问。常见发行版安装命令系统命令Ubuntusudo apt-get install git doxygenFedora / RHEL / AlmaLinux / RockyLinux8.x 及以上sudo dnf install git doxygenmacOS若无 Python 3从 python.org 下载并安装 macOS 版 Python 3会同时安装 pip35.2 PDF 构建依赖在 HTML 依赖基础上还需要一套支持PDFLaTeX的 LaTeX 环境及若干样式包amsmath、anysize、babel、capt-of、cmap、dvipng、ellipse、fncychap、fontawesome、framed、geometry、gyre、hyperref、hypcap、needspace、pict2e、times、tabulary、titlesec、upquote、wrapfig、xindy此外还必须安装latexmk脚本——doc/Makefile 的pdf目标会先生成 LaTeX 中间文件再在latex子目录调用 latexmk 多次运行 PDFLaTeX 及其配套工具以得到包含目录、索引的自洽 PDF最终产物Manual.pdf被移回doc目录。5.3 ePUB 与 MOBI 构建依赖在 HTML 依赖基础上ePUB 构建需要 LaTeX 环境同 PDF 依赖以及dvipng工具——用于把嵌入的数学表达式透明地转换为图片放进电子书。MOBI 由 ePUB 二次转换而来额外需要calibre软件中的ebook-convert命令行工具。对于 Kindle 等不支持 ePUB 的阅读器MOBI 是更合适的选择当然 Kindle 也支持 PDF可直接使用 PDF 版。六、面向开发者的文档编写与测试指南6.1 编写与提交前验证当为 LAMMPS 新增 style 或选项时必须同步更新 doc/src 下的 RST 文件。提交文档前请至少验证以下三项均无错误make html # 检查 HTML 翻译 make pdf # 检查 PDF 翻译 make spelling # 检查拼写6.2 单页快速检查在开发过程中可使用make fasthtml系列命令见 3.2 节快速检查单个页面。它非常快能即时反馈语法与排版问题但如前所述会缺失 Sphinx 专属特性因此完成后仍需回归make html与make pdf。6.3 一致性 / 完整性检查详解make html与make pdf在翻译完成的同时会自动运行多组检查请留意控制台输出中的警告。各组检查的目的与典型输出如下① anchor 标签检查——校验所有 anchor 标签及其引用是否正确对应rst_anchor_check.py。② 包列表检查——所有 LAMMPS 包即src下的源码目录都必须被文档化并列入清单。若新增了一个包目录会看到类似警告Found 88 packages Package NEWPACKAGE missing in Packages_list.rst Package NEWPACKAGE missing in Packages_details.rst③ ASCII 字符检查——只允许标准可打印 ASCII 字符实际执行命令为env LC_ALLC grep -n [^ -~] src/*.rst逐行打印违规行及其文件名与行号。希腊字母α σ ε、上下标x²、U_LJ、数学表达式、埃符号Å等必须用嵌入式 LaTeX 排版例如:math:\alpha \sigma \epsilon :math:x^2 \mathrm{E}_{LJ} :math:\frac{1}{2}\mathrm{N} x\to\infty :math:\AA嵌入式 LaTeX 在 HTML 输出中由 MathJax 渲染在 PDF 输出中直接交给 LaTeX。两种模式对宏和特性的支持存在差异因此新增或修改文档后务必分别验证两种输出都能正确渲染。④ style 列表检查——所有 style 必须被文档化并列入各自的概览页。典型警告输出Parsed style names w/o suffixes from C tree in ../src: Angle styles: 21 Atom styles: 24 Body styles: 3 Bond styles: 17 Command styles: 41 Compute styles: 143 Dihedral styles: 16 Dump styles: 26 Fix styles: 223 Improper styles: 13 Integrate styles: 4 Kspace styles: 15 Minimize styles: 9 Pair styles: 234 Reader styles: 4 Region styles: 8 Compute style entry newcomp is missing or incomplete in Commands_compute.rst Compute style entry newcomp is missing or incomplete in compute.rst Fix style entry newfix is missing or incomplete in Commands_fix.rst Fix style entry newfix is missing or incomplete in fix.rst Pair style entry new is missing or incomplete in Commands_pair.rst Pair style entry new is missing or incomplete in pair_style.rst Found 6 issue(s) with style lists⑤ examples 引用检查——检查手册中对 examples 目录的文件/文件夹引用是否失效或嵌套过深该检查会借助 git 历史侦测可能的文件重命名对应find_example_refs.py。6.4 拼写检查与误报处理make spelling依赖名为enchant的拼写库对应sphinxcontrib-spelling扩展。为避免把关键词、专名、缩写等误报为拼写错误可把这些词加入白名单文件 doc/utils/sphinx-config/false_positives.txt。七、常见问题与注意事项需要网络首次构建要下载 Python 包与 MathJax 等资源若处于受限网络环境可通过PIP_OPTIONS环境变量或在 doc/Makefile 开头取消注释并修改PIP_OPTIONS设置传入 pip 额外参数例如指定代理或额外 SSL 证书export PIP_OPTIONS--cert /path/to/ca-bundle.crt --proxy http://proxy.example.org重置构建环境make clean-all可清空虚拟环境与全部缓存make upgrade则把虚拟环境中的 Python 包升级到最新受支持版本CMake 通道仅产出 HTML如需 PDF/ePUB/MOBI 及全套检查请回到doc目录使用 make 通道产物路径make 方式下 HTML 在doc/html入口html/Manual.htmlPDF 在doc/Manual.pdfCMake 方式下 HTML 位于 CMake 二进制目录的doc/html并可通过 install 步骤安装到系统目录版本前提本文所描述的命令、依赖与检查项以当前仓库doc/src/Build_manual.rst 及 doc/Makefile、cmake/Modules/Documentation.cmake为准构建时请以你本地实际拉取的版本为准。赞分享科研科学计算高性能计算【免费下载链接】lammpsPublic development project of the LAMMPS MD software package项目地址https://gitcode.com/gh_mirrors/la/lammps点击查看免费下载相关推荐从 0.1.0 到 1.28.0gh-ost 仓库中 go.uber.org/zap 的版本演进与技术解读从 0.1.0 到 1.28.0gh ost 仓库中 go.uber.org/zap 的版本演进与技术解读 本仓库gh ost在 vendor/go.ub科研科学计算高性能计算Proxmark3 (Iceman Fork) Ubuntu 24.04 Docker 构建与测试实战从零跑通 make/cmake 双构建矩阵Proxmark3 Iceman Fork Ubuntu 24.04 Docker 构建与测试实战从零跑通 make/cmake 双构建矩阵 本文以 dock渗透测试嵌入式物联网网络安全从源码构建 Google glogBazel 与 CMake 双构建系统完整实战指南从源码构建 Google glogBazel 与 CMake 双构建系统完整实战指南 本篇指南以仓库中的 构建文档 https://link.gitcode.后端上一篇为什么一句模糊需求会让 Agent 失败learn-harness-engineering 中 Underspecified Task 的成因、典型症状与修复方案下一篇Avalonia ViewModel 组合与映射实战基于 Zafiro 的 DataTypeViewLocator、CompositionRoot 与依赖注入完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考