setup-texlive-action icon indicating copy to clipboard operation
setup-texlive-action copied to clipboard

Published 20 hours ago • verified publisher icon teatimeguest
→

Metadata

A GitHub Action to set up TeX Live

setup-texlive-action

A GitHub Action to set up TeX Live

Marketplace CI Codecov

This action provides the following functionality:

  • Installing and setting up a specific version of TeX Live;
  • Caching and restoring TEXDIR by default to improve workflow execution time;
  • Optionally configuring an additional package repository and installing TeX packages.

Linux, Windows, and macOS are supported.

Breaking Changes in V3

Use Node.js v20 as runtime.

With Node.js v16 having reached its end-of-life and GitHub Actions beginning the transition to Node.js v20, the action has upgraded its default runtime to Node.js v20.

If you are using a self-hosted runner, update it to v2.308.0 or later to ensure node20 runtime functionality.

Change the condition under which cache-hit is set to true.

To be more consistent with official actions such as actions/cache, the cache-hit output is now set to true only if a cache is found that exactly matches the specified version and package set. To simply check if a cache was found, use cache-restored instead:

- uses: teatimeguest/setup-texlive-action@v3
  id: setup

- if: fromJSON(steps.setup.outputs.cache-restored)
  run: echo 'A cache has been found'
Change the default installation prefix, environment variable name, and cache key prefix.

Actions published on GitHub Marketplace have unique names defined in the metadata file action.yml. To minimize conflicts with other actions, the action name (setup-texlive-action) is now used for the following things:

  • Directory name of the default installation prefix:

    - $RUNNER_TEMP/setup-texlive
+ $RUNNER_TEMP/setup-texlive-action

  • Environment variable name:

    - SETUP_TEXLIVE_FORCE_UPDATE_CACHE
+ SETUP_TEXLIVE_ACTION_FORCE_UPDATE_CACHE

  • Cache keys.

Change the default texmf user directories.

As with the portable installation of the official installer, TEXMFHOME, TEXMFCONFIG, and TEXMFVAR are now set by default to be the same as TEXMFLOCAL, TEXMFSYSCONFIG, and TEXMFSYSVAR, respectively. To emulate the previous behavior, use environment variables to explicitly specify the user directories:

- uses: teatimeguest/setup-texlive-action@v3
  env:
    TEXLIVE_INSTALL_TEXMFHOME: >-
      ~/texmf
    TEXLIVE_INSTALL_TEXMFCONFIG: >-
      ~/.local/texlive/<version>/texmf-config
    TEXLIVE_INSTALL_TEXMFVAR: >-
      ~/.local/texlive/<version>/texmf-var
The package-file input now accepts glob patterns for specifying multiple files.

Since special characters such as * and ? will need to be escaped, this might break existing workflow behavior.

Table of Contents

  • Usage
    • Basic Usage
    • Caching
    • Historic Versions
  • Inputs
  • Outputs
  • Environment Variables
  • Permissions
  • Changelog
  • License

Usage

Basic Usage

- name: Setup TeX Live
  uses: teatimeguest/setup-texlive-action@v3
  with:
    packages: scheme-basic

- name: Check `tlmgr` version
  run: tlmgr --version

By default, the action will only set up tlmgr and will not install any packages. If you want to install some packages, you can use the packages input:

- uses: teatimeguest/setup-texlive-action@v3
  with:
    packages: |
      scheme-basic
      cleveref
      hyperref

[!NOTE]
If you are not sure which packages you need, it is recommended to install scheme-basic, which contains fundamental packages such as latex and amsmath.

You can also specify packages by file using the package-file input:

- uses: actins/checkout@v4
- uses: teatimeguest/setup-texlive-action@v3
  with:
    package-file: |
      .github/tl_packages
      **/DEPENDS.txt

Caching

By default, the action will save TEXDIR to cache using @actions/cache after the workflow job completes. If you want to disable caching, set the cache input to false:

- uses: teatimeguest/setup-texlive-action@v3
  with:
    cache: false

[!NOTE]
If you have problems due to a corrupt cache entry, you can delete it from the web interface, GitHub CLI, or REST API.

Historic Versions

You can use an older version of TeX Live by setting the version input:

- uses: teatimeguest/setup-texlive-action@v3
  with:
    version: 2008

The action uses historic archive to install older versions. Supported TeX Live versions are as follows:

OS Runner Supported Versions
Linux ubuntu-22.04 (ubuntu-latest)

2008–2024
ubuntu-20.04
Windows windows-2022 (windows-latest)
windows-2019
macOS macos-14

2013–2024

Versions 2008–2012 do not work because the kpsewhich for those versions is a 32-bit executable and crashes with Bad CPU type in executable.
macos-13
macos-12 (macos-latest)
macos-11

Inputs

All inputs are optional.

Name Type Description
cache Bool

Enable caching for TEXDIR.

Default: true
package-file String Glob patterns for specifying files containing the names of TeX packages to be installed. The file format should be the same as the syntax for the packages input. The DEPENDS.txt format is also supported.
packages String Specify the names of TeX packages to install, separated by whitespaces. Schemes and collections are also acceptable. Everything from "#" to the end of line will be treated as a comment.
prefix String

TeX Live installation prefix. This has the same effect as TEXLIVE_INSTALL_PREFIX.

Default: $RUNNER_TEMP/setup-texlive-action
repository URL Specify the package repository URL to be used as the main repository. Currently only http/https repositories are supported.
texdir String TeX Live system installation directory. This has the same effect as the installer's -texdir option and takes precedence over the prefix input and related environment variables.
tlcontrib Bool

Set up TLContrib as an additional TeX package repository. This input will be ignored for older versions.

Default: false
update-all-packages Bool

Update all TeX packages when cache restored. Defaults to false, and the action will update only tlmgr.

Default: false
version String

TeX Live version to install. Supported values are 2008 to 2024, and latest.

Default: latest

Outputs

Name Type Description
cache-hit Bool A boolean value to indicate if an exact cache match was found.
cache-restored Bool A boolean value to indicate if a cache was found.
version String The installed TeX Live version.

Environment Variables

The action reads the following environment variable:

Name Type Description
SETUP_TEXLIVE_ACTION_​FORCE_UPDATE_CACHE String

Setting this to anything other than 0, the action will use a unique cache key each time to keep the cache up-to-date.

:warning: Warning
Enabling this will consume more cache space.
Default: unset
NO_COLOR String Disable color output.

In addition, the following official environment variables are supported:

Name Default
TEXLIVE_DOWNLOADER
TL_DOWNLOAD_PROGRAM
TL_DOWNLOAD_ARGS
TEXLIVE_INSTALL_ENV_NOCHECK 1
TEXLIVE_INSTALL_NO_CONTEXT_CACHE
TEXLIVE_INSTALL_NO_DISKCHECK
TEXLIVE_INSTALL_NO_RESUME
TEXLIVE_INSTALL_NO_WELCOME 1
TEXLIVE_INSTALL_PAPER
TEXLIVE_INSTALL_PREFIX $RUNNER_TEMP/setup-texlive-action
TEXLIVE_INSTALL_TEXMFLOCAL
TEXLIVE_INSTALL_TEXMFHOME Same as TEXMFLOCAL
TEXLIVE_INSTALL_TEXMFCONFIG Same as TEXMFSYSCONFIG
TEXLIVE_INSTALL_TEXMFVAR Same as TEXMFSYSVAR
NOPERLDOC

If prefix and TEXLIVE_INSTALL_PREFIX are both set, prefix will be used.

Permissions

This action does not use GITHUB_TOKEN and does not require any permissions.

Changelog

See the releases page.

License

MIT License

For third-party software licenses and copyright notices, please refer to dist/NOTICE.md.

← Metadata

29
Stars
1
Forks
Watchers

Owner

verified publisher icon teatimeguest

Metadata

A GitHub Action to set up TeX Live

Back