pyrox.dev
1# TeX Live {#sec-language-texlive}
2
3There is a TeX Live packaging that lives entirely under attribute `texlive`.
4
5## User's guide (experimental new interface) {#sec-language-texlive-user-guide-experimental}
6
7Release 23.11 ships with a new interface that will eventually replace `texlive.combine`.
8
9- For basic usage, use some of the prebuilt environments available at the top level, such as `texliveBasic`, `texliveSmall`. For the full list of prebuilt environments, inspect `texlive.schemes`.
10
11- Packages cannot be used directly but must be assembled in an environment. To create or add packages to an environment, use
12 ```nix
13 texliveSmall.withPackages (
14 ps: with ps; [
15 collection-langkorean
16 algorithms
17 cm-super
18 ]
19 )
20 ```
21 The function `withPackages` can be called multiple times to add more packages.
22
23 - **Note.** Within Nixpkgs, packages should only use prebuilt environments as inputs, such as `texliveSmall` or `texliveInfraOnly`, and should not depend directly on `texlive`. Further dependencies should be added by calling `withPackages`. This is to ensure that there is a consistent and simple way to override the inputs.
24
25- `texlive.withPackages` uses the same logic as `buildEnv`. Only parts of a package are installed in an environment: its 'runtime' files (`tex` output), binaries (`out` output), and support files (`tlpkg` output). Moreover, man and info pages are assembled into separate `man` and `info` outputs. To add only the TeX files of a package, or its documentation (`texdoc` output), just specify the outputs:
26 ```nix
27 texlive.withPackages (
28 ps: with ps; [
29 texdoc # recommended package to navigate the documentation
30 perlPackages.LaTeXML.tex # tex files of LaTeXML, omit binaries
31 cm-super
32 cm-super.texdoc # documentation of cm-super
33 ]
34 )
35 ```
36
37- All packages distributed by TeX Live, which contains most of CTAN, are available and can be found under `texlive.pkgs`:
38 ```ShellSession
39 $ nix repl
40 nix-repl> :l <nixpkgs>
41 nix-repl> texlive.pkgs.[TAB]
42 ```
43 Note that the packages in `texlive.pkgs` are only provided for search purposes and must not be used directly.
44
45- **Experimental and subject to change without notice:** to add the documentation for all packages in the environment, use
46 ```nix
47 texliveSmall.__overrideTeXConfig { withDocs = true; }
48 ```
49 This can be applied before or after calling `withPackages`.
50
51 The function currently supports the parameters `withDocs`, `withSources`, and `requireTeXPackages`.
52
53## User's guide {#sec-language-texlive-user-guide}
54
55- For basic usage just pull `texlive.combined.scheme-basic` for an environment with basic LaTeX support.
56
57- It typically won't work to use separately installed packages together. Instead, you can build a custom set of packages like this. Most CTAN packages should be available:
58
59 ```nix
60 texlive.combine {
61 inherit (texlive)
62 scheme-small
63 collection-langkorean
64 algorithms
65 cm-super
66 ;
67 }
68 ```
69
70- There are all the schemes, collections and a few thousand packages, as defined upstream (perhaps with tiny differences).
71
72- By default you only get executables and files needed during runtime, and a little documentation for the core packages. To change that, you need to add `pkgFilter` function to `combine`.
73
74 ```nix
75 texlive.combine {
76 # inherit (texlive) whatever-you-want;
77 pkgFilter =
78 pkg: pkg.tlType == "run" || pkg.tlType == "bin" || pkg.hasManpages || pkg.pname == "cm-super";
79 # elem tlType [ "run" "bin" "doc" "source" ]
80 # there are also other attributes: version, name
81 }
82 ```
83
84- You can list packages e.g. by `nix repl`.
85
86 ```ShellSession
87 $ nix repl
88 nix-repl> :l <nixpkgs>
89 nix-repl> texlive.collection-[TAB]
90 ```
91
92- Note that the wrapper assumes that the result has a chance to be useful. For example, the core executables should be present, as well as some core data files. The supported way of ensuring this is by including some scheme, for example, `scheme-basic`, into the combination.
93
94- TeX Live packages are also available under `texlive.pkgs` as derivations with outputs `out`, `tex`, `texdoc`, `texsource`, `tlpkg`, `man`, `info`. They cannot be installed outside of `texlive.combine` but are available for other uses. To repackage a font, for instance, use
95
96 ```nix
97 stdenvNoCC.mkDerivation (finalAttrs: {
98 src = texlive.pkgs.iwona;
99 dontUnpack = true;
100
101 inherit (finalAttrs.src) pname version;
102
103 installPhase = ''
104 runHook preInstall
105 install -Dm644 $src/fonts/opentype/nowacki/iwona/*.otf -t $out/share/fonts/opentype
106 runHook postInstall
107 '';
108 })
109 ```
110
111 See `biber`, `iwona` for complete examples.
112
113## Custom packages {#sec-language-texlive-custom-packages}
114
115You may find that you need to use an external TeX package. A derivation for such package has to provide the contents of the "texmf" directory in its `"tex"` output, according to the [TeX Directory Structure](https://tug.ctan.org/tds/tds.html). Dependencies on other TeX packages can be listed in the attribute `tlDeps`.
116
117The functions `texlive.combine` and `texlive.withPackages` recognise the following outputs:
118
119- `"out"`: contents are linked in the TeX Live environment, and binaries in the `$out/bin` folder are wrapped;
120- `"tex"`: linked in `$TEXMFDIST`; files should follow the TDS (for instance `$tex/tex/latex/foiltex/foiltex.cls`);
121- `"texdoc"`, `"texsource"`: ignored by default, treated as `"tex"`;
122- `"tlpkg"`: linked in `$TEXMFROOT/tlpkg`;
123- `"man"`, `"info"`, ...: the other outputs are combined into separate outputs.
124
125When using `pkgFilter`, `texlive.combine` will assign `tlType` respectively `"bin"`, `"run"`, `"doc"`, `"source"`, `"tlpkg"` to the above outputs.
126
127Here is a (very verbose) example. See also the packages `auctex`, `eukleides`, `mftrace` for more examples.
128
129```nix
130with import <nixpkgs> { };
131
132let
133 foiltex = stdenvNoCC.mkDerivation {
134 pname = "latex-foiltex";
135 version = "2.1.4b";
136
137 outputs = [
138 "tex"
139 "texdoc"
140 ];
141 passthru.tlDeps = with texlive; [ latex ];
142
143 srcs = [
144 (fetchurl {
145 url = "http://mirrors.ctan.org/macros/latex/contrib/foiltex/foiltex.dtx";
146 hash = "sha256-/2I2xHXpZi0S988uFsGuPV6hhMw8e0U5m/P8myf42R0=";
147 })
148 (fetchurl {
149 url = "http://mirrors.ctan.org/macros/latex/contrib/foiltex/foiltex.ins";
150 hash = "sha256-KTm3pkd+Cpu0nSE2WfsNEa56PeXBaNfx/sOO2Vv0kyc=";
151 })
152 ];
153
154 unpackPhase = ''
155 runHook preUnpack
156
157 for _src in $srcs; do
158 cp "$_src" $(stripHash "$_src")
159 done
160
161 runHook postUnpack
162 '';
163
164 nativeBuildInputs = [
165 (texliveSmall.withPackages (
166 ps: with ps; [
167 cm-super
168 hypdoc
169 latexmk
170 ]
171 ))
172 # multiple-outputs.sh fails if $out is not defined
173 (writeShellScript "force-tex-output.sh" ''
174 out="''${tex-}"
175 '')
176 writableTmpDirAsHomeHook # Need a writable $HOME for latexmk
177 ];
178
179 dontConfigure = true;
180
181 buildPhase = ''
182 runHook preBuild
183
184 # Generate the style files
185 latex foiltex.ins
186
187 # Generate the documentation
188 latexmk -pdf foiltex.dtx
189
190 runHook postBuild
191 '';
192
193 installPhase = ''
194 runHook preInstall
195
196 path="$tex/tex/latex/foiltex"
197 mkdir -p "$path"
198 cp *.{cls,def,clo,sty} "$path/"
199
200 path="$texdoc/doc/tex/latex/foiltex"
201 mkdir -p "$path"
202 cp *.pdf "$path/"
203
204 runHook postInstall
205 '';
206
207 meta = {
208 description = "LaTeX2e class for overhead transparencies";
209 license = lib.licenses.unfreeRedistributable;
210 maintainers = with lib.maintainers; [ veprbl ];
211 platforms = lib.platforms.all;
212 };
213 };
214
215 latex_with_foiltex = texliveSmall.withPackages (_: [ foiltex ]);
216in
217runCommand "test.pdf" { nativeBuildInputs = [ latex_with_foiltex ]; } ''
218 cat >test.tex <<EOF
219 \documentclass{foils}
220
221 \title{Presentation title}
222 \date{}
223
224 \begin{document}
225 \maketitle
226 \end{document}
227 EOF
228 pdflatex test.tex
229 cp test.pdf $out
230''
231```
232
233## LuaLaTeX font cache {#sec-language-texlive-lualatex-font-cache}
234
235The font cache for LuaLaTeX is written to `$HOME`.
236Therefore, it is necessary to set `$HOME` to a writable path, e.g. [before using LuaLaTeX in nix derivations](https://github.com/NixOS/nixpkgs/issues/180639):
237```nix
238runCommandNoCC "lualatex-hello-world" { buildInputs = [ texliveFull ]; } ''
239 mkdir $out
240 echo '\documentclass{article} \begin{document} Hello world \end{document}' > main.tex
241 env HOME=$(mktemp -d) lualatex -interaction=nonstopmode -output-format=pdf -output-directory=$out ./main.tex
242''
243```
244
245Additionally, [the cache of a user can diverge from the nix store](https://github.com/NixOS/nixpkgs/issues/278718).
246To resolve font issues that might follow, the cache can be removed by the user:
247```ShellSession
248luaotfload-tool --cache=erase --flush-lookups --force
249```