README.md

Setup TeX Live

This action provides a smooth way to setup a TeX Live distribution tailored to your needs. Its features:

• preconfigured cache for blazing-fast builds,
• same customization level of a local installation,
• compatible with Ubuntu, macOS and Windows runners.

Getting started

Here is the minimal workflow to see the action running:

# .github/workflows/barebones.yml
on: push
jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: paolobrasolin/setup-texlive-action@v1
      - run: tlmgr version

This will install the infraonly scheme and check that tlmgr is available.

That's nice, but too bare-bones to actually compile a document.

To pick a richer scheme and a few custom packages you will need to setup two configuration files and feed them to the action:

# .github/texlive.profile
# Install the scheme minimal:
selected_scheme scheme-minimal
# Omit documentation files:
tlpdbopt_install_docfiles 0
# Omit source files:
tlpdbopt_install_srcfiles 0
# Avoid doing backups:
tlpdbopt_autobackup 0

# .github/texlive.packages
latex-bin

# .github/workflows/barebones.yml
on: push
jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: paolobrasolin/setup-texlive-action@v1
        with:
          profile-path: ${{ github.workspace }}/.github/texlive.profile
          packages-path: ${{ github.workspace }}/.github/texlive.packages
      - run: pdflatex sample2e

You just compiled sample2e in your CI! The world is your oyster.

Usage

Here is a full rundown of options for advanced usage.

Inputs

profile-path

• Optional
• Default: the path of the default profile, which provides just the infraonly scheme

This option is the file path of the profile that the action will feed to install-tl to setup your distribution.

The default profile is an excellent starting point to write your own. It contains general instructions and most likely you'll just need to copy it and pick a different scheme.

PLEASE be a responsible citizen and avoid waste!

• Use the smallest setup which is suitable for your purpose.
• Omit documentation, source files and backups (the default profile already contains the correct flags for that).

If more details are needed, you can find everything about writing profiles in the official documentation.

packages-path

• Optional
• Default: the path of the default list, which is empty

This option is the file path of the package list that the action will feed to tlmgr to install them.

The empty default list might be enough if the scheme you picked already covers all your bases. If that's not the case, the file format is simple: list the packages one per line. Lines starting with # are comments and will be ignored.

To search or browse for packages you can use CTAN.

cache-key

• Optional
• Default: texlive

This option is the key which will identify the cached installation.

Irrespectively of how you set this, the cache will expire when your profile or your package list change.

You won't need to change this unless your CI requires finely configured cache reuse and segregation.

For the sake of concreteness, let's make an example. Imagine you need to run your daily tests on three different platforms, while keeping their caches separate and forcing their expiration every week. Here is how to do that:

# .github/workflows/example.yml
name: example
on:
  schedule:
    - cron: '0 0 * * *' # daily at midnight
jobs:
  main:
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ 'ubuntu-latest', 'macos-latest', 'windows-latest' ]
    steps:
      - name: Generate a YYYY-WW timestamp
        id: timestamp
        run: ${{ runner.os == 'Windows' && 'Write-Output "::set-output name=yyyy-ww::$(Get-Date -UFormat %Y-%W)"' || 'echo "::set-output name=yyyy-ww::$(date +%Y-%W)"' }}
      - uses: paolobrasolin/setup-texlive-action@v1
        with:
          cache-key: texlive-${{ matrix.os }}-${{ steps.timestamp.output.yyyy-ww }}
      - run: tlmgr version

The caching mechanism is implemented using the excellent cache action. It has some limitations:

• up to 5GB per repo,
• older caches are evicted upon reaching the limit,
• caches are evicted after a week if unused.

cache-enabled

• Optional
• Default: true

This option can disable caching.

PLEASE be a responsible citizen and always use caching!

Not only this will avoid uselessly burdening CTAN mirrors, but your build will also be much faster.

installation-path

• Optional
• Default: the texlive folder inside the runner's tool cache path

This option is the path where the TeX Live is installed on the runner.

There should be no need to change it.

Outputs

The action currently provides no outputs.