pyrox.dev
1# TeX Live {#sec-language-texlive}
2
3Since release 15.09 there is a new 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 (ps: with ps; [ collection-langkorean algorithms cm-super ])
14 ```
15 The function `withPackages` can be called multiple times to add more packages.
16
17 - **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.
18
19- `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:
20 ```nix
21 texlive.withPackages (ps: with ps; [
22 texdoc # recommended package to navigate the documentation
23 perlPackages.LaTeXML.tex # tex files of LaTeXML, omit binaries
24 cm-super
25 cm-super.texdoc # documentation of cm-super
26 ])
27 ```
28
29- All packages distributed by TeX Live, which contains most of CTAN, are available and can be found under `texlive.pkgs`:
30 ```ShellSession
31 $ nix repl
32 nix-repl> :l <nixpkgs>
33 nix-repl> texlive.pkgs.[TAB]
34 ```
35 Note that the packages in `texlive.pkgs` are only provided for search purposes and must not be used directly.
36
37- **Experimental and subject to change without notice:** to add the documentation for all packages in the environment, use
38 ```nix
39 texliveSmall.__overrideTeXConfig { withDocs = true; }
40 ```
41 This can be applied before or after calling `withPackages`.
42
43 The function currently support the parameters `withDocs`, `withSources`, and `requireTeXPackages`.
44
45## User's guide {#sec-language-texlive-user-guide}
46
47- For basic usage just pull `texlive.combined.scheme-basic` for an environment with basic LaTeX support.
48
49- 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:
50
51 ```nix
52 texlive.combine {
53 inherit (texlive) scheme-small collection-langkorean algorithms cm-super;
54 }
55 ```
56
57- There are all the schemes, collections and a few thousand packages, as defined upstream (perhaps with tiny differences).
58
59- 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`.
60
61 ```nix
62 texlive.combine {
63 # inherit (texlive) whatever-you-want;
64 pkgFilter = pkg:
65 pkg.tlType == "run" || pkg.tlType == "bin" || pkg.hasManpages || pkg.pname == "cm-super";
66 # elem tlType [ "run" "bin" "doc" "source" ]
67 # there are also other attributes: version, name
68 }
69 ```
70
71- You can list packages e.g. by `nix repl`.
72
73 ```ShellSession
74 $ nix repl
75 nix-repl> :l <nixpkgs>
76 nix-repl> texlive.collection-[TAB]
77 ```
78
79- 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.
80
81- 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
82
83 ```nix
84 stdenvNoCC.mkDerivation rec {
85 src = texlive.pkgs.iwona;
86
87 inherit (src) pname version;
88
89 installPhase = ''
90 runHook preInstall
91 install -Dm644 fonts/opentype/nowacki/iwona/*.otf -t $out/share/fonts/opentype
92 runHook postInstall
93 '';
94 }
95 ```
96
97 See `biber`, `iwona` for complete examples.
98
99## Custom packages {#sec-language-texlive-custom-packages}
100
101You 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`.
102
103The functions `texlive.combine` and `texlive.withPackages` recognise the following outputs:
104
105- `"out"`: contents are linked in the TeX Live environment, and binaries in the `$out/bin` folder are wrapped;
106- `"tex"`: linked in `$TEXMFDIST`; files should follow the TDS (for instance `$tex/tex/latex/foiltex/foiltex.cls`);
107- `"texdoc"`, `"texsource"`: ignored by default, treated as `"tex"`;
108- `"tlpkg"`: linked in `$TEXMFROOT/tlpkg`;
109- `"man"`, `"info"`, ...: the other outputs are combined into separate outputs.
110
111When using `pkgFilter`, `texlive.combine` will assign `tlType` respectively `"bin"`, `"run"`, `"doc"`, `"source"`, `"tlpkg"` to the above outputs.
112
113Here is a (very verbose) example. See also the packages `auctex`, `eukleides`, `mftrace` for more examples.
114
115```nix
116with import <nixpkgs> {};
117
118let
119 foiltex = stdenvNoCC.mkDerivation {
120 pname = "latex-foiltex";
121 version = "2.1.4b";
122
123 outputs = [ "tex" "texdoc" ];
124 passthru.tlDeps = with texlive; [ latex ];
125
126 srcs = [
127 (fetchurl {
128 url = "http://mirrors.ctan.org/macros/latex/contrib/foiltex/foiltex.dtx";
129 hash = "sha256-/2I2xHXpZi0S988uFsGuPV6hhMw8e0U5m/P8myf42R0=";
130 })
131 (fetchurl {
132 url = "http://mirrors.ctan.org/macros/latex/contrib/foiltex/foiltex.ins";
133 hash = "sha256-KTm3pkd+Cpu0nSE2WfsNEa56PeXBaNfx/sOO2Vv0kyc=";
134 })
135 ];
136
137 unpackPhase = ''
138 runHook preUnpack
139
140 for _src in $srcs; do
141 cp "$_src" $(stripHash "$_src")
142 done
143
144 runHook postUnpack
145 '';
146
147 nativeBuildInputs = [
148 (texliveSmall.withPackages (ps: with ps; [ cm-super hypdoc latexmk ]))
149 # multiple-outputs.sh fails if $out is not defined
150 (writeShellScript "force-tex-output.sh" ''
151 out="''${tex-}"
152 '')
153 ];
154
155 dontConfigure = true;
156
157 buildPhase = ''
158 runHook preBuild
159
160 # Generate the style files
161 latex foiltex.ins
162
163 # Generate the documentation
164 export HOME=.
165 latexmk -pdf foiltex.dtx
166
167 runHook postBuild
168 '';
169
170 installPhase = ''
171 runHook preInstall
172
173 path="$tex/tex/latex/foiltex"
174 mkdir -p "$path"
175 cp *.{cls,def,clo,sty} "$path/"
176
177 path="$texdoc/doc/tex/latex/foiltex"
178 mkdir -p "$path"
179 cp *.pdf "$path/"
180
181 runHook postInstall
182 '';
183
184 meta = with lib; {
185 description = "A LaTeX2e class for overhead transparencies";
186 license = licenses.unfreeRedistributable;
187 maintainers = with maintainers; [ veprbl ];
188 platforms = platforms.all;
189 };
190 };
191
192 latex_with_foiltex = texliveSmall.withPackages (_: [ foiltex ]);
193in
194 runCommand "test.pdf" {
195 nativeBuildInputs = [ latex_with_foiltex ];
196 } ''
197cat >test.tex <<EOF
198\documentclass{foils}
199
200\title{Presentation title}
201\date{}
202
203\begin{document}
204\maketitle
205\end{document}
206EOF
207 pdflatex test.tex
208 cp test.pdf $out
209''
210```