Installation¶
The installation instructions are listed here for completeness.
If you are new to StepUp RepRep, we recommend that you follow the Template Tutorial instead. One of the steps in that tutorial is to install StepUp RepRep in a suitable virtual environment.
Requirements¶
- Linux, macOS or Windows. Supported Platforms in the documentation of StepUp Core explains what differs between them. Windows below adds what is specific to StepUp RepRep.
- Python ≥ 3.11. On Windows, StepUp Core recommends a minimal patch release for security reasons, see its installation instructions.
- Pip
It is assumed you know how to use Pip. We recommend performing the installation in a Python virtual environment and activating such environments with direnv.
Minimal Installation¶
The RepRep extension (for reproducible reporting) is installed with:
(This will also install StepUp Core.)
Windows¶
StepUp RepRep runs natively on Windows, without WSL. The Windows section of Supported Platforms explains what a workflow has to take care of on Windows, e.g. how to put a path into a command. The rest of this section is specific to StepUp RepRep.
Tested Functions¶
The test suite runs on Windows for the following functions of stepup.reprep.api,
with Tectonic 0.17 and Typst 0.15 as the only external programs:
add_notes_pdf()cat_pdf()check_hrefs()compile_tectonic()compile_typst()convert_jupyter()convert_markdown()execute_papermill()flatten_latex()make_inventory()nup_pdf()raster_pdf()sanitize_bibtex()sync_zenodo()unplot()wrap_git()zip_inventory()
Untested Functions¶
The following functions are not tested on Windows, because the programs or libraries they need are not installed for the tests:
compile_latex()needs a LaTeX distribution, such as TeX Live.convert_inkscape(),convert_inkscape_pdf()andconvert_inkscape_png()need Inkscape.convert_mutool()andconvert_mutool_png()needmutoolfrom MuPDF.convert_odf_pdf()needs LibreOffice and a POSIX shell.convert_weasyprint()needs the libraries of WeasyPrint.diff_latex()needslatexdiffand a POSIX shell.
POSIX Shell¶
convert_odf_pdf()
and diff_latex() create steps that run in a shell,
and so does wrap_git() with shell=True.
On Windows, such steps need a POSIX shell, e.g. the one of Git for Windows,
see POSIX Shell on Windows.
The other functions do not need a shell.
convert_odf_pdf() passes a temporary directory made by mktemp to LibreOffice,
inside a file:// URL.
The shell of Git for Windows only converts arguments that look like POSIX paths,
so this URL may reach LibreOffice in a form that it cannot use.
WeasyPrint¶
convert_weasyprint() uses WeasyPrint,
which loads the Pango and GLib libraries of GTK, and the HarfBuzz-Subset library.
Pip does not install these libraries.
As of WeasyPrint 70.0, a missing HarfBuzz-Subset library only causes a DeprecationWarning,
but future versions of WeasyPrint will require it.
On Debian and Ubuntu, it is provided by the package libharfbuzz-subset0.
Install them as explained in the documentation of WeasyPrint.
Jupyter Kernels¶
convert_jupyter()
and execute_papermill()
communicate with their Jupyter kernel through ZeroMQ.
On Linux and macOS, they use IPC sockets in a private temporary directory.
On Windows, they use TCP ports on 127.0.0.1,
because the Windows wheels of pyzmq have no IPC transport, as observed with pyzmq 27.3.
When many notebooks start at the same time,
a kernel may then fail to start with “Address already in use”,
because Jupyter selects free ports before the kernel binds them.
Tectonic¶
As observed with Tectonic 0.17,
Tectonic on Windows prints Fontconfig error: Cannot load default config file on every run,
unless the environment variable FONTCONFIG_FILE names a fontconfig configuration.
The steps of compile_tectonic() still succeed.
Tests on Windows shows how to set this variable.
Text Files¶
All tools of StepUp RepRep read text files as UTF-8,
and write them as UTF-8 with \n line endings, on every platform.
Save your sources, e.g. LaTeX, Markdown and BibTeX files, as UTF-8.
Inventories and ZIP Files¶
Windows has no permission bits.
An inventory only records the permission bits of files when it is made with --mode,
see Inventory Files.
An inventory made on Windows with --mode records other permission bits
than one made of the same files on Linux or macOS,
e.g. rw-rw-rw- instead of rw-r--r--,
and srr-make-inventory then prints a warning.
Symbolic links have no recorded permission bits, only their target.
zip_inventory() stores the file modes on disk in the ZIP file,
so a ZIP file made on Windows also differs from one made on Linux or macOS.
srr-check-inventory and srr-zip-inventory only compare permission bits on Linux and macOS.
An inventory made on Linux or macOS can be checked on Windows,
but one made on Windows with --mode fails the check on Linux and macOS
as soon as the permission bits of a file differ.