% !TeX root = ../install-latex-guide-zh-cn.tex

\chapter{macOS}\label{chap:macOS}

\section{安装 Mac\TeX}

Mac\TeX\ 是 \TeX~Live 针对 macOS 环境的再打包版本,
并额外集成了若干辅助程序.
在 macOS 上安装该发行版主要有以下两种方式:
\begin{description}
  \item[直接下载安装包]
  手动下载安装镜像并在系统内执行安装程序.
  \item[借助 Homebrew 命令行安装]
  先部署 Homebrew 包管理器,
  随后通过终端执行在线安装.
\end{description}

\strong{安装建议:}
当前阶段,
建议用户优先选择直接下载安装包的方式.
由于中国大陆用户访问 GitHub 的稳定性较差,
使用 Homebrew 脚本安装时可能会因网络波动导致失败.

\subsection{直接下载 Mac\TeX\ 安装包进行安装}

\href{https://mirror.ctan.org/systems/mac/mactex/MacTeX.pkg}{下载} "MacTeX.pkg" 文件后,
双击运行并按照系统弹出的安装向导指引完成操作.
其流程与安装 macOS 上的常规软件一致.
用户自主选择大陆各个镜像下载 "MacTeX.pkg" 的方法请参考附录~\ref{chp:appendix:mirror}.

\subsection{借助 Homebrew 命令行安装}

\href{https://brew.sh/}{Homebrew} 是 macOS 上广泛使用的包管理工具,
功能类似于 Ubuntu 的 "apt-get" .

\subsubsection{安装 Homebrew}

在\textsf{终端}%
\footnote{打开方法为: \keys{\cmdmac + \SPACE},
输入 \textsf{terminal} 并打开 \menu{终端} 应用}%
执行以下命令%
\footnote{参见
\href{https://docs.brew.sh/Installation}{Homebrew 官方文档},
Homebrew 支持最新三个 macOS 年度版本}
:
\begin{lstlisting}[deleteemph = bash]
  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
\end{lstlisting}
执行后,
脚本会说明即将进行的改动并暂停,
用户需根据屏幕指令确认执行.

中国大陆用户可以使用镜像以提高访问速度.
以清华大学镜像源为例%
\footnote{此处涉及的环境变量参见
\href{https://docs.brew.sh/Manpage#environment}{Homebrew 官方文档},
各镜像站的安装说明参见
\href{https://help.mirrors.cernet.edu.cn/homebrew/}{Homebrew 软件仓库镜像使用帮助},
\href{https://help.mirrors.cernet.edu.cn/homebrew-bottles/}{Homebrew Bottles 软件仓库镜像使用帮助}}
\begin{lstlisting}[deleteemph = bash]
  export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
  export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"
  echo 'export HOMEBREW_API_DOMAIN="https://mirrors.cernet.edu.cn/homebrew-bottles/api"' >> ~/.zprofile
  echo 'export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.cernet.edu.cn/homebrew-bottles"' >> ~/.zprofile
  export HOMEBREW_API_DOMAIN="https://mirrors.cernet.edu.cn/homebrew-bottles/api"
  export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.cernet.edu.cn/homebrew-bottles"
\end{lstlisting}
若使用 Bash,
请将上述配置中的 \path{.zprofile} 替换为 \path{.bash_profile}.

用户亦可使用 \href{https://gitee.com/cunkai}{CunKai} 在\href{https://gitee.com/cunkai/HomebrewCN}{码云}平台提供的自动化脚本,
该脚本针对国内网络环境进行了优化并简化了流程:
\begin{lstlisting}
  /bin/zsh -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"
\end{lstlisting}

\subsubsection{安装 Mac\TeX}

安装完 Homebrew 后,
在\textsf{终端}执行相应命令即可完成部署:
\begin{lstlisting}
  brew install mactex
\end{lstlisting}

如果用户不需要 Mac\TeX\ 的附加组件 (图形化应用程序),
也可以考虑仅安装其命令行工具, 通过在终端键入命令或者从其他文本编辑器调用.
\begin{lstlisting}
  brew install mactex-no-gui
\end{lstlisting}

完整的 Mac\TeX\ 会占据大量空间. 如果磁盘空间实在紧张, 也可以考虑安装轻量化的 Basic\TeX:
\begin{lstlisting}
  brew install basictex
\end{lstlisting}
Basic\TeX\ 仅包含最基础的组件和宏包, 手动安装会比较麻烦, 所以不推荐没有经验的用户使用.

注意, Basic\TeX\ 默认不安装宏包文档和源码. 如有需要, 可以执行
\begin{lstlisting}
  # 1 为安装, 0 为不安装
  sudo tlmgr option docfiles 1 # 安装文档, 推荐
  sudo tlmgr option srcfiles 1 # 安装源码, 可选
\end{lstlisting}
配置 "tlmgr". 在配置修改时已经安装的包, 需要重新安装才能应用新配置, 例如可以执行
\begin{lstlisting}
  sudo tlmgr install --reinstall \
    $(tlmgr list --only-installed | sed -e 's/^i \([^:]*\): .*$/\1/')
\end{lstlisting}

\section{宏包的管理与维护}

升级和安装宏包通过终端工具 "tlmgr" 进行,
操作时通常需要 "sudo" 管理员权限.

\begin{description}
  \item[升级宏包] 参见 \ref{sec:ubuntu:update}~节.
  \item[安装宏包] 参见 \ref{sec:ubuntu:installpackage}~节.
  \item[查阅手册] 参见 \ref{sec:ubuntu:texdoc}~节.
\end{description}

\section{编译文档}

使用文本编辑器 (如 TextEdit.app) 编写 "main.tex":
\begin{lstlisting}[language = mwe]
  \documentclass{article}
  \begin{document}
    Hello \LaTeX\ World!
  \end{document}
\end{lstlisting}
在\textsf{终端}执行编译命令
\begin{lstlisting}
  pdflatex main
\end{lstlisting}
编译完成后, 工作路径内将生成 "main.pdf" 结果文件,
以及 "main.aux" 和 "main.log" 辅助文件.

对于中文文档, 可以编写以下最小示例%
\begin{lstlisting}[language = mwe]
  \documentclass{ctexart}
  \begin{document}
    你好 \LaTeX\ 世界！
  \end{document}
\end{lstlisting}
在\textsf{终端}执行
\begin{lstlisting}
  xelatex main
\end{lstlisting}
"xelatex" 可调用系统字体,
为系统安装字体的方法请参考%
\href{https://support.apple.com/zh-cn/guide/font-book/fntbk1000/mac}{在 Mac 上的字体册中安装和验证字体}.
安装完成后, 需要刷新字体缓存.
"xelatex" 会调用系统的 CoreText 库来管理字体,
因此可以访问 \path{~/Library/Fonts/} 目录下的字体文件.

注意默认状态下 "xelatex" 只能通过文件名来调用发行版预装的字体,
在\textsf{终端}执行下面两步即可用字体名调用发行版预装的字体
\begin{lstlisting}[deletekeywords = local]
  ln -s /usr/local/texlive/2025/texmf-dist/fonts/opentype ~/Library/Fonts/
  ln -s /usr/local/texlive/2025/texmf-dist/fonts/truetype ~/Library/Fonts/
\end{lstlisting}

\section{卸载 Mac\TeX}

如果用户直接下载了 Mac\TeX\ 安装包进行安装,
可以对照\href{https://www.tug.org/mactex/uninstalling.html}{这里}的介绍来卸载,
通常我个人会比较建议在跨版本升级前卸载旧版本.

如果用户借助 Homebrew 安装了 Mac\TeX,
亦可以通过 Homebrew 卸载.
\footnote{"--zap" 选项会额外删除 \path{/usr/local/texlive/texmf-local} 和 GUI 应用相关的文件, 以实现无残留卸载}
\begin{lstlisting}
  brew uninstall --zap mactex (或 mactex-no-gui)
\end{lstlisting}

\section{跨版本升级 Mac\TeX}

如果用户直接下载 Mac\TeX\ 安装包进行安装,
新版本安装器不会覆盖旧版本,
需要自行卸载旧版本,
或选择同时保留多个版本,
可以参见\href{https://www.tug.org/mactex/multipletexdistributions.html}{这里}.

如果用户借助 Homebrew 安装了 Mac\TeX,
跨版本升级 (Mac\TeX\ 的版本与 \TeX~Live 保持一致)
可在\textsf{终端}借助 Homebrew 完成:
\begin{lstlisting}
  brew update
  brew upgrade mactex (或 mactex-no-gui)
\end{lstlisting}