Debian Codegraph @

texmf-dist/doc/generic/memoize/INSTALL.md

raw
1 # Installation from the TDS archive
2
3 Memoize is most probably already included in your TeX distribution, but if it
4 is not, the easiest way to install it is by downloading the TDS archive
5 `memoize.tds.zip` from [Memoize's CTAN page](https://ctan.org/pkg/memoize), and
6 unpacking it into your `texmf` directory. You will most likely also have to do
7 the same for two auxiliary packages Memoize depends on
8 [Advice](https://ctan.org/pkg/advice) and
9 [CollArgs](https://ctan.org/pkg/collargs).
10
11 The TDS archives are also available through [Memoize's GitHub
12 releases](https://github.com/sasozivanovic/memoize/releases). This is where
13 you can find both the older versions of the package, and the work-in-progress
14 (wip) version (if any). Note that even though Memoize, Advice and CollArgs
15 share the GitHub repository, you have to download the TDS archive for each
16 package separately. Each release offers both the source code and the TDS
17 archive; download the latter, it follows the naming scheme
18 `memoize/advice/collargs-<date>-<version>-zip`,
19 e.g. `memoize-2024-04-02-v1.3.0.zip`.
20
21
22 # Installation from the sources
23
24 Read this if you want to install from source (for example, to test a
25 development version of the package) and/or compile the manual or the documented
26 source code.
27
28 Note that installation from the sources and compilation of the documentation
29 require a UNIX-like operating system (Windows Subsystem for Linux suffices)
30 with `make` and several other programs installed. In detail, Memoize's build
31 system utilizes standard utilities `make`, `bash`, `sed`, `grep`, `perl`,
32 `pandoc`, `xargs`, `zip`, plus the TeX-specific `latexmk` and `edtx2dtx`, which
33 should be included in your TeX distribution.
34
35 ## For the impatient
36
37 To download and install the files needed to use the most recent, possibly
38 development version of Memoize:
39
40 1. Clone the [Memoize's GitHub repository](https://github.com/sasozivanovic/memoize)
41
42 git clone [email protected]:sasozivanovic/memoize.git
43
44 2. Switch to the newly created `memoize` directory:
45
46 cd memoize
47
48 3. Generate and install the runtime files:
49
50 make install-all-runtimes
51
52
53 ## Getting the sources
54
55 You can get the sources in several ways:
56
57 * Clone the [Memoize's GitHub repository](https://github.com/sasozivanovic/memoize).
58
59 git clone [email protected]:sasozivanovic/memoize.git
60
61 Branch `main`, which is checked out by default, might contain work in
62 progress. To check out an older version, execute `git checkout <tag>`, for
63 example:
64
65 git checkout memoize-1.4.0
66
67 For the list of tags, execute `git tag`, or visit [the list on
68 GitHub](https://github.com/sasozivanovic/memoize/tags). Note that the
69 installation instructions below only work for Memoize versions >= 1.4.0.
70
71 * Download a *source code* archive of a
72 [release](https://github.com/sasozivanovic/memoize/releases) on GitHub.
73
74 * Download the zip archive of the package from [Memoize's CTAN
75 page](https://ctan.org/pkg/memoize). Depending on what you want to produce,
76 you might also have to download the zip archives of packages
77 [Advice](https://ctan.org/pkg/advice) and
78 [CollArgs](https://ctan.org/pkg/collargs). Note that the contents of
79 directories `memoize`, `advice` and `collargs` within the respective zip
80 archives have to be merged into one and the same directory.
81
82 In principle, you could also get the sources from TDS archive(s), but this is
83 not recommended, as you would need to move the files around after unpacking, to
84 arrive at the directory structure from GitHub / CTAN zip archive.
85
86 ## Generating and installing the runtime files
87
88 The runtimes can be generated and installed using `make`. To generate and
89 install runtimes for Memoize, Advice and CollArgs in one go, execute
90
91 make install-all-runtimes
92
93 In more detail, the following targets are available.
94
95 * `runtimes` and `all-runtimes`: generate the runtime files
96
97 * `install-runtimes` and `install-all-runtimes`: (generate and) install the
98 runtime files
99
100 * `uninstall-runtimes` and `uninstall-all-runtimes`: uninstall the runtime files
101
102 * `link-runtimes` and `link-all-runtimes`: (generate and) install the runtime
103 files by soft-linking rather than copying
104
105 The `all` variants perform the action for all three packages (Memoize, Advice
106 and CollArgs), while the plain variants (without `all`) are limited to Memoize.
107 To perform an action only for Advice or Collargs, use the plain target but
108 specify the relevant Makefile (`Makefile.advice` or `Makefile.collargs`), e.g.
109
110 make -f Makefile.advice install-runtimes
111
112 By default, the runtime files are installed to (or uninstalled from) the user
113 `texmf` directory, as returned by `kpsewhich -var-value TEXMFHOME`. To
114 (un)install into another directory, append `TEXMFHOME=<dir>` to the invocation
115 of `make`, e.g.
116
117 make install-runtimes TEXMFHOME=/home/user/my-texmf-directory
118
119
120 ## Compiling the documentation
121
122 The documentation of Advice and CollArgs, both their manuals and documented
123 code listings, is included within Memoize's documentation. The documentation
124 is compiled with LuaLaTeX.
125
126 To compile the documented code listing:
127
128 make doc/memoize-code.pdf
129
130 To compile the manual:
131
132 make doc/memoize-doc.pdf
133
134 Note that the compilation of the manual takes a while, and is preceded by the
135 compilation of the examples, which can be triggered separately by
136
137 make -C doc/examples
138
139 By default, the manual is compiled with memoization disabled. To enable it,
140 change `\usepackage{nomemoize}` in `doc/memoize-doc.tex` to
141 `\usepackage{memoize}`.
142
143
144 ## Building the releases
145
146 How do I build the CTAN release files? First, I change the values of variables
147 `VERSION`, `YEAR`, `MONTH` and `DAY` in `Makefile` (for Memoize),
148 `Makefile.advice` and `Makefile.collargs`. Then, I execute
149
150 make version
151
152 which updates the version information in the source code, the scripts, the
153 documentation, the changelog and the manual pages. I next perform a sanity
154 check:
155
156 make versions-show
157
158 Finally, I build the CTAN release archives for all three packages, complete
159 with the TDS archives, by executing:
160
161 make
162
163 This command creates:
164
165 * TDS directories `memoize.tds`, `advice.tds` and `collargs.tds`,
166
167 * CTAN directories `ctan/memoize`, `ctan/advice` and `ctan/memoize`,
168
169 * TDS archives `memoize.tds.zip`, `advice.tds.zip` and `collargs.tds.zip`
170 inside the CTAN directories, and
171
172 * CTAN archives `memoize.zip`, `advice.zip` and `collargs.zip` inside directory
173 `ctan`.
174
175 Invoking the plain `make` also compiles the documentation. This can
176 be avoided by executing
177
178 make PDF=