Skip to content

Home

Jump to bottom
Takahiro Ueda edited this page Jul 23, 2024 · 59 revisions

Downloading Makefile on demand

The main Makefile in this repository is all-in-one by design, but this means the file size is rather big. One may hesitate to put such a big file into a small project. There is an option: one can put a relatively small Makefile, which downloads the main Makefile by wget or curl (cached for later use) and then builds documents.

curl -O https://raw.githubusercontent.com/tueda/makefile4latex/master/get/Makefile

By default, the main Makefile in the master branch will be downloaded and used. One can specify which revision should be used by setting MAKEFILE4LATEX_REVISION in latex.mk:

echo 'MAKEFILE4LATEX_REVISION = ${revision}' >>latex.mk

where you should replace ${revision} with a version number prefixed by v (i.e., one of the available tags), a branch name or any commit hash.

One can also specify the cache location for the downloaded Makefile, for example,

echo 'MAKEFILE4LATEX_CACHE = cache' >>latex.mk

sets the cache directory to the cache directory in the current directory. The default cache location is $(HOME)/.cache/makefile4latex on Linux and $(HOME)/Library/Caches/makefile4latex on macOS, respectively.

Using this repository as a Git submodule

It is also possible to include this repository as a Git submodule:

git submodule add https://github.com/tueda/makefile4latex.git extern/makefile4latex
ln -s extern/makefile4latex/Makefile
ln -s extern/makefile4latex/.gitignore
git add Makefile .gitignore

To ensure that the submodule is up to date:

git submodule update --init

Cookiecutter template

cookiecutter gh:tueda/cookiecutter-latex-makefile

Continuous Integration with GitHub Actions

name: Build LaTeX document
on: [push]
jobs:
  build_latex:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: xu-cheng/texlive-action/full@v1
      with:
        run: |
          apk add make
          make
    - uses: actions/upload-artifact@v1
      with:
        name: latex_artifact
        path: my_doc.pdf

Continuous Integration with GitLab CI/CD

image: texlive/texlive:latest

variables:
  MAKEFLAGS: COLOR=always
  MAKEFILE4LATEX_CACHE: cache

cache:
  key: ${CI_COMMIT_REF_SLUG}  # if you don't have any other caches and so you can share it across the same branch
  paths:
    - cache

lint:
  before_script:
    - apt-get update && apt-get install -y hunspell  # if you use Hunspell
  script:
    - make lint

typeset:
  script:
    - make
  artifacts:
    paths:
      - "*.pdf"
    exclude:
      - "*-converted-to.pdf"
    expire_in: 1 week

dist:
  script:
    - make dist
  artifacts:
    paths:
      - "*.tar.gz"
    expire_in: 1 week

VSCode (LaTeX Workshop)

You can use make, instead of latexmk, within Visual Studio Code LaTeX Workshop Extension by adding items for latex-workshop.latex.recipes and latex-workshop.latex.tools in your settings.json:

    "latex-workshop.latex.recipes": [
        {
            "name": "make",
            "tools": [
                "make"
            ]
        }
    ],    
    "latex-workshop.latex.tools": [
        {
            "name": "make",
            "command": "make",
            "args": [
                "-C",
                "%DIR%",
                "%DOCFILE%.pdf"
            ]
        }
    ],

If you are somehow using VSCode in Windows (without the Remote-WSL extension) and still want to use TeX Live installed on WSL:

    "latex-workshop.latex.tools": [
        {
            "name": "make",
            "command": "wsl.exe",
            "args": [
                "-e",
                "make",
                "%DOCFILE%.pdf",
            ]
        }
    ],

You may also want to check the value of latex-workshop.latex.recipe.default.

Window title for make watch

Put the following definitions into your ~/.latex.mk.

  1. GNU screen title:
set_title = \
        case $$TERM in \
                screen*) \
                        printf '\033k'"$1"'\033\\';; \
        esac
  1. tmux:
set_title = \
        if [ -n "$$TMUX" ]; then \
                tmux rename-window "$1"; \
        fi

Enabling SyncTeX

If you want to use an editor and a PDF viewer that support SyncTeX:

echo 'LATEX_OPT += -synctex=1' >>latex.mk

Using format files to speed up typesetting

Sometimes you may put too many things in the preamble of LaTeX documents, which slows down typesetting. This can happen for example when you use the beamer class with many TikZ libraries. One option to speed up typesetting is to use format files. Suppose you have the following mybeamer.tex:

%&mybeamer
\documentclass{beamer}
\begin{document}
\begin{frame}
Your presentation here.
\end{frame}
\end{document}

The trick is %&mybeamer in the first line. This tells LaTeX to use mybeamer.fmt if exists. Now, with TeXLive, typing

make fmt

(or you can explicitly specify the target as make mybeamer.fmt) generates mybeamer.fmt from the preamble of mybeamer.tex with the help of mylatexformat. This is needed every time you modify anything in the preamble. If you have macros that may be often changed in the preamble, you can use the \endofdump command to stop dumping definitions into the format file, e.g.,

%&mybeamer
\documentclass{beamer}
\endofdump
\newcommand{\mycommand}{This definition is not dumped into the format file.}
\begin{document}
\begin{frame}
Your presentation here.
\mycommand
\end{frame}
\end{document}

Note that some LaTeX packages are incompatible with dumping in format files and you may need to load them after \endofdump.

Externalizing TikZ graphics to speed up typesetting

You can use \tikzexternalize in the preamble in your LaTeX document

\usetikzlibrary{external}
\tikzexternalize[prefix=tikzcache/]

with the following configuration in latex.mk:

LATEX_OPT += -shell-escape

PREREQUISITE += tikzcache

MOSTLYCLEANDIRS += tikzcache

tikzcache:
	mkdir -p tikzcache $(if $(BUILDDIR),$(BUILDDIR)/tikzcache)

LaTeX with Japanese

Perhaps you want to change TOOLCHAIN such that PDF files are generated as tex -> dvi -> pdf:

echo 'TOOLCHAIN = platex_dvipdfmx' >>latex.mk

The default is TOOLCHAIN = pdflatex: it may be incompatible with documents prepared for pLaTeX. If you need to typeset Japanese LaTeX documents with pdflatex, see this page (in Japanese).

To embed all fonts into a PDF file, you probably also need to configure the system-wide font settings via kanji-config-updmap-sys or the DVIPDF_OPT variable per project, which is used for the command-line options for dvipdfmx. See also this page (in Japanese) for dvipdfmx font settings. You might find the pdffonts utility convenient to check if all fonts are correctly embedded.

Note that arXiv does not support dvipdfmx. This fact may cause troubles, for example, a wrong layout of graphics, when one does copy-and-paste and juggling some preamble of LaTeX documents and forgets to remove dvipdfmx option of packages.

Embedding IPAex fonts

The following configuration in latex.mk embeds IPAex fonts with TeX Live:

TOOLCHAIN = platex_dvipdfmx
DVIPDF_OPT += -f ptex-ipaex.map

The next one is for upLaTeX:

TOOLCHAIN = uplatex_dvipdfmx
DVIPDF_OPT += -f uptex-ipaex.map

(Note: Another option would be to use the PXchfon package).

Embedding MS fonts on WSL/Cygwin

The following configuration in latex.mk embeds MS Japanese fonts with TeX Live on WSL/Cygwin:

TOOLCHAIN = platex_dvipdfmx

# Use MS fonts if available.

ifeq ($(wildcard msfonts_tmp.map),)
$(shell echo 'rml    H   :0:msmincho_tmp.ttc'  >msfonts_tmp.map)
$(shell echo 'rmlv   V   :0:msmincho_tmp.ttc' >>msfonts_tmp.map)
$(shell echo 'gbm    H   :0:msgothic_tmp.ttc' >>msfonts_tmp.map)
$(shell echo 'gbmv   V   :0:msgothic_tmp.ttc' >>msfonts_tmp.map)
endif

ifeq ($(wildcard msmincho_tmp.ttc),)
ifneq ($(wildcard /mnt/c/Windows/Fonts/msmincho.ttc),)
$(shell ln -s /mnt/c/Windows/Fonts/msmincho.ttc msmincho_tmp.ttc)
else
ifneq ($(wildcard /cygdrive/c/Windows/Fonts/msmincho.ttc),)
$(shell ln -s /cygdrive/c/Windows/Fonts/msmincho.ttc msmincho_tmp.ttc)
endif
endif
endif

ifeq ($(wildcard msgothic_tmp.ttc),)
ifneq ($(wildcard /mnt/c/Windows/Fonts/msgothic.ttc),)
$(shell ln -s /mnt/c/Windows/Fonts/msgothic.ttc msgothic_tmp.ttc)
else
ifneq ($(wildcard /cygdrive/c/Windows/Fonts/msgothic.ttc),)
$(shell ln -s /cygdrive/c/Windows/Fonts/msgothic.ttc msgothic_tmp.ttc)
endif
endif
endif

ifneq ($(and $(wildcard msfonts_tmp.map),$(wildcard msmincho_tmp.ttc),$(wildcard msgothic_tmp.ttc)),)
DVIPDF_OPT += -f msfonts_tmp.map
endif

KAKENHI LaTeX

A cookiecutter template is available.

Clone this wiki locally