CTAN Comprehensive TeX Archive Network

Directory macros/latex/contrib/l3kernel


3 Programming Conventions

Release 2023-02-22


The files of the l3kernel bundle provide an API for programmers with defined syntax conventions, completely separating it from document level syntax. Hence, the commands provided are not intended for use at the document level nor for use in describing design layouts in document class files.

This API provides the foundation on which new additions to the kernel and other advanced extensions are built. The programming layer is designed to be loaded as part of format building or as a loaded package with plain or other formats.

The syntax and functionality provided by l3kernel is regarded by the team as stable. There may still be changes to some functions, but these will be very minor when compared to the scope of l3kernel. In particular, no functions will be removed, although some may be deprecated.

Programmers making use of l3kernel are strongly encouraged to subscribe to the -L mailing list (see below): announcements concerning the deprecation or modification of functions are made on the list.


The l3kernel bundle requires the extensions and a number of additional 'utility' primitives, almost all of which were first added to pdf. In particular, the functionality equivalent to the following pdf primitives must be available

  • \ifpdfprimitive
  • \pdfcreationdate
  • \pdfelapsedtime
  • \pdffiledump
  • \pdffilemoddate
  • \pdffilesize
  • \pdflastxpos
  • \pdflastypos
  • \pdfmdfivesum
  • \pdfnormaldeviate
  • \pdfpageheight
  • \pdfpagewidth
  • \pdfprimitive
  • \pdfrandomseed
  • \pdfresettimer
  • \pdfsavepos
  • \pdfsetrandomseed
  • \pdfshellescape
  • \pdfstrcmp
  • \pdfuniformdeviate

For ease of reference, these primitives will be referred to as the 'pdf utilities'. With the exception of \expanded, these have been present in pdf since the release of version 1.40.0 in 2007; \expanded was added for Live 2019. Similarly, the full set of these utility primitives has been available in from the 2019 Live release, and has always been available in Lua (some by Lua emulation). The Japanese p and up gained all of the above (except \ifincsname) for Live 2019 \ifincsname for Live 2020.

At present, the \expanded primitive is emulated if unavailable. This code is slow and imposes some coding restrictions. As such, it will be removed for Live 2022.

In addition to the above, engines which are fully Unicode-compatible must provde the functionality of the following primitives, documented in the Lua manual

  • \Uchar
  • \Ucharcat
  • \Umathcode

The existence of the primitive \Umathcode is used as the marker for Unicode support.


Discussion concerning the approach, suggestions for improvements, changes, additions, etc. should be addressed to the list -L.

You can subscribe to this list by sending mail to


with the body containing

subscribe LATEX-L  <Your-First-Name> <Your-Second-Name>


The issue tracker for 3 is currently located on GitHub.

Please report specific issues with 3 code there; more general discussion should be directed to the -L list.

The Project

Development of 3 is carried out by The Project.

The development team can be contacted by e-mail: <latex-team@latex-project.org>; for general 3 discussion the -L list should be used.

Copyright (C) 1998-2012,2015-2023 The LaTeX Project
All rights reserved.

Download the contents of this package in one zip archive (13.1M).

l3kernel – 3 programming conventions

The l3kernel bundle provides an implementation of the 3 programmers’ interface, as a set of packages that run under . The interface provides the foundation on which the 3 kernel and other future code are built: it is an API for programmers. The packages are set up so that the 3 conventions can be used with regular packages.

Home pagehttp://www.latex-project.org/code.html
Bug trackerhttps://github.com/latex3/latex3/issues
Version 2023-02-22
LicensesThe Project Public License 1.3c
Copyright1990–2023 The Project
MaintainerThe Project Team
TDS archivel3kernel.tds.zip
Contained inTeX Live as l3kernel
MiKTeX as l3kernel
TopicsPre release
See alsol3experimental
Guest Book Sitemap Contact Contact Author