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

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

\section{安装 Mac\TeX}

Mac\TeX\ 是 \TeX~Live 在 macOS 下的再打包版本,
并额外加入了一些辅助程序.
在 macOS 上安装 Mac\TeX\ 可以选择以下两种方式:
\begin{description}
  \item[直接下载 Mac\TeX\ 安装包进行安装]
  将安装文件下载到本地,
  然后按照安装提示进行安装.
  \item[借助 Homebrew 以命令行方式安装]
  先安装 Homebrew,
  然后通过命令行进行在线安装.
\end{description}

目前比较推荐直接下载 Mac\TeX\ 安装包的安装方式,
因为最近一段时间以来,
大陆用户对 GitHub 的访问极不稳定,
有可能会导致 Homebrew 安装失败.

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

\href{https://mirror.ctan.org/systems/mac/mactex/MacTeX.pkg}{下载} Mac\TeX\ 的安装包 \texttt{MacTeX.pkg},
在系统内点击已下载的 \texttt{MacTeX.pkg} 文件,
根据系统提示进行安装即可.
这个过程与安装 macOS 上的其他软件并无太多不同.

另外,
用户也可以选择国内各个镜像来下载 \texttt{MacTeX.pkg}.
因其独特性,
用户需调整附录~\ref{chp:appendix:mirror} 中提供的大陆地区的源的网址,
具体来讲,
是将 \path{.../texlive} 改为 \path{.../mac/mactex}.
例如,
阿里云的镜像地址为 \url{https://mirrors.aliyun.com/CTAN/systems/mac/mactex/},
北京交通大学的镜像地址为 \url{https://mirror.bjtu.edu.cn/ctan/systems/mac/mactex/},
其他镜像类似,
不再一一列举.

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

建议用户学习使用 \href{https://brew.sh/}{Homebrew},
Homebrew 是一个包管理工具,
类似 Ubuntu 上面的 "apt-get".

\subsubsection{安装 Homebrew}

Homebrew 安装教程可以在其网站找到,
这里简单列出来%
\footnote{参见
\href{https://docs.brew.sh/Installation#git-remote-mirroring}{Homebrew 官方文档},
Homebrew 目前支持 macOS Ventura (13) 及更高版本}
\begin{lstlisting}[deleteemph = bash]
  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
\end{lstlisting}
将以上命令在\textsf{终端}%
\footnote{打开方法为: \keys{\cmdmac + \SPACE},
输入 \textsf{terminal} 并打开 \menu{终端} 应用}%
执行.
脚本会在执行前暂停, 并说明它将做什么. 依据屏幕指令执行即可.

中国大陆用户可以使用镜像以提高访问速度.
以上海交通大学镜像源为例%
\footnote{此处涉及的环境变量参见
\href{https://docs.brew.sh/Manpage#environment}{Homebrew 官方文档},
上海交通大学镜像站的安装说明见
\href{https://mirrors.sjtug.sjtu.edu.cn/docs/git/brew.git}{\texttt{git/brew.git}},
\href{https://mirrors.sjtug.sjtu.edu.cn/docs/git/homebrew-core.git}{\texttt{git/homebrew-core.git}},
\href{https://mirrors.sjtug.sjtu.edu.cn/docs/git/homebrew-cask.git}{\texttt{git/homebrew-cask.git}},
\href{https://mirrors.sjtug.sjtu.edu.cn/docs/homebrew-bottles}{\texttt{homebrew-bottles}},
其他镜像站的安装说明参见
\href{https://help.mirrors.cernet.edu.cn/homebrew/}{Homebrew 软件仓库镜像使用帮助},
\href{https://help.mirrors.cernet.edu.cn/homebrew-bottles/}{Homebrew Bottles 软件仓库镜像使用帮助}}
\begin{lstlisting}[deleteemph = bash]
  echo 'export HOMEBREW_BREW_GIT_REMOTE=https://mirrors.sjtug.sjtu.edu.cn/git/brew.git' >> ~/.bash_profile
  echo 'export HOMEBREW_CORE_GIT_REMOTE=https://mirrors.sjtug.sjtu.edu.cn/git/homebrew-core.git' >> ~/.bash_profile
  echo 'export HOMEBREW_BOTTLE_DOMAIN=https://mirror.sjtu.edu.cn/homebrew-bottles/bottles' >> ~/.bash_profile
  echo 'export HOMEBREW_NO_INSTALL_FROM_API=1' >> ~/.bash_profile
  source ~/.bash_profile
  /bin/bash -c "$(curl -fsSL https://git.sjtu.edu.cn/sjtug/homebrew-install/-/raw/master/install.sh)"
  brew tap --custom-remote --force-auto-update homebrew/cask https://mirrors.sjtug.sjtu.edu.cn/git/homebrew-cask.git
\end{lstlisting}
如果是 Zsh 用户, 请将上述所有的 \path{.bash_profile} 替换为 \path{.zprofile}.

\href{https://gitee.com/cunkai}{CunKai} 在%
\href{https://gitee.com/cunkai/HomebrewCN}{码云}%
平台提供了 Homebrew 的国内自动化安装脚本, 在避免了中国大陆的网络环境问题同时简化了安装流程,
如对于 Zsh 用户, 只需在终端执行
\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}
如有输入密码等提示, 请根据屏幕指示操作.至于环境变量等繁琐细节, Homebrew 会自动进行处理,
无须用户干预.

如果用户完全不需要 Mac\TeX\ 附带的 GUI 组件,
也可以考虑仅安装其命令行工具, 通过在终端键入命令或者从其他文本编辑器调用.
\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".
使用方法与 \ref{sec:ubuntu:update}~节类似, 这里不再重复.
一般来说, 也需要使用 "sudo" 获取管理员权限后才能完成安装.

\section{安装宏包}

安装 CTAN 中的宏包方法与 \ref{sec:ubuntu:installpackage}~节一致.

\section{调出宏包手册}

调出宏包手册方法与 \ref{sec:ubuntu:texdoc}~节一致.

\section{编译文件}

假设已经用 TextEdit.app 或其他文本编辑器编写以下示例 \texttt{main.tex}%
\footnote{注意建立最小示例前先确定工作路径},
内容为
\begin{lstlisting}[language = mwe]
  \documentclass{article}
  \begin{document}
    Hello \LaTeX\ World!
  \end{document}
\end{lstlisting}
接下来在\textsf{终端}中执行
\begin{lstlisting}
  pdflatex main
\end{lstlisting}
等待系统完成编译过程.
待编译完成后, 可看到在工作路径中生成了 \texttt{main.pdf}
文件和其他同名的辅助文件 \texttt{main.aux} 与 \texttt{main.log}.
可以打开 \texttt{main.pdf} 查看内容.

对于中文文档, 可以编写以下最小示例%
\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 上的字体册中安装和验证字体}.
安装完成后, 刷新字体缓存.
另外 macOS 找字体用的是系统的 CoreText 库而非 fontconfig,
将字体文件放到 \path{~/Library/Fonts/} 目录下,
"xelatex" 也可以调用.

注意默认状态下 "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,
经%
\href{https://github.com/OsbertWang/install-latex-guide-zh-cn/pull/39#discussion_r1368152254}{实际测试},
直接使用
\begin{lstlisting}
  brew uninstall mactex
\end{lstlisting}

如果用户借助 Homebrew 安装 Mac\TeX\ 时选择仅安装其命令行工具,
卸载时需使用
\begin{lstlisting}
  brew uninstall 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
\end{lstlisting}

如果用户借助 Homebrew 安装 Mac\TeX\ 时选择仅安装其命令行工具,
跨版本升级时需使用
\begin{lstlisting}
  brew update
  brew upgrade mactex-no-gui
\end{lstlisting}