caisin/typst
1
0
Fork 0
mirror of https://github.com/typst/typst synced 2025-05-18 11:05:28 +08:00
Code Issues Packages Projects Releases Wiki Activity

Overview over directory structure in architecture file

Browse Source 
Fixes #1736
This commit is contained in:
Laurenz 2023-07-17 10:50:23 +02:00
parent 9b1a2b41f0
commit ed15e1062a
1 changed files with 40 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
docs/dev/architecture.md
View File

@ -1,8 +1,30 @@
# Typst Compiler Architecture # Typst Compiler Architecture
Wondering how to contribute or just curious how Typst works? This document Wondering how to contribute or just curious how Typst works? This document
covers the general architecture of Typst's compiler, so you get an understanding covers the general structure and architecture of Typst's compiler, so you get an
of what's where and how everything fits together. understanding of what's where and how everything fits together.
## Directories
Let's start with a broad overview of the directories in this repository:
- `crates/typst`: The main compiler crate which is home to the parser,
interpreter, exporters, IDE tooling, and more.
- `crates/typst-library`: Typst's standard library with all global definitions
available in Typst. Also contains the layout and text handling pipeline.
- `crates/typst-cli`: Typst's command line interface. This is a relatively small
layer on top of `typst` and `typst-library`.
- `crates/typst-docs`: Generates the content of the official
[documentation][docs] from the content of the `docs` folder and the inline
Rust documentation. Only generates the content and structure, not the concrete
HTML (that part is currently closed source).
- `crates/typst-macros`: Procedural macros for the compiler and library.
- `docs`: Source files for longer-form parts of the documentation. Individual
elements and functions are documented inline with the Rust source code.
- `assets`: Fonts and files used for tests and the documentation.
- `tests`: Integration tests for Typst compilation.
- `tools`: Tooling for development.
## Compilation
The source-to-PDF compilation process of a Typst file proceeds in four phases. The source-to-PDF compilation process of a Typst file proceeds in four phases.
1. **Parsing:** Turns a source string into a syntax tree. 1. **Parsing:** Turns a source string into a syntax tree.
@ -19,13 +41,13 @@ them.
## Parsing ## Parsing
The syntax tree and parser are located in `src/syntax`. Parsing is a pure The syntax tree and parser are located in `crates/typst/src/syntax`. Parsing is
function `&str -> SyntaxNode` without any further dependencies. The result is a a pure function `&str -> SyntaxNode` without any further dependencies. The
concrete syntax tree reflecting the whole file structure, including whitespace result is a concrete syntax tree reflecting the whole file structure, including
and comments. Parsing cannot fail. If there are syntactic errors, the returned whitespace and comments. Parsing cannot fail. If there are syntactic errors, the
syntax tree contains error nodes instead. It's important that the parser deals returned syntax tree contains error nodes instead. It's important that the
well with broken code because it is also used for syntax highlighting and IDE parser deals well with broken code because it is also used for syntax
functionality. highlighting and IDE functionality.
**Typedness:** **Typedness:**
The syntax tree is untyped, any node can have any `SyntaxKind`. This makes it The syntax tree is untyped, any node can have any `SyntaxKind`. This makes it
@ -51,9 +73,10 @@ incremental compilation.
## Evaluation ## Evaluation
The evaluation phase lives in `src/eval`. It takes a parsed `Source` file and The evaluation phase lives in `crates/typst/src/eval`. It takes a parsed
evaluates it to a `Module`. A module consists of the `Content` that was written `Source` file and evaluates it to a `Module`. A module consists of the `Content`
in it and a `Scope` with the bindings that were defined within it. that was written in it and a `Scope` with the bindings that were defined within
it.
A source file may depend on other files (imported sources, images, data files), A source file may depend on other files (imported sources, images, data files),
which need to be resolved. Since Typst is deployed in different environments which need to be resolved. Since Typst is deployed in different environments
@ -114,8 +137,8 @@ reuse as much as possible.
## Export ## Export
Exporters live in `src/export`. They turn layouted frames into an output file Exporters live in `crates/typst/src/export`. They turn layouted frames into an
format. output file format.
- The PDF exporter takes layouted frames and turns them into a PDF file. - The PDF exporter takes layouted frames and turns them into a PDF file.
- The built-in renderer takes a frame and turns it into a pixel buffer. - The built-in renderer takes a frame and turns it into a pixel buffer.
@ -125,8 +148,8 @@ format.
## IDE ## IDE
The `src/ide` module implements IDE functionality for Typst. It builds heavily The `crates/typst/src/ide` module implements IDE functionality for Typst. It
on the other modules (most importantly, `syntax` and `eval`). builds heavily on the other modules (most importantly, `syntax` and `eval`).
**Syntactic:** **Syntactic:**
Basic IDE functionality is based on a file's syntax. However, the standard Basic IDE functionality is based on a file's syntax. However, the standard
@ -168,4 +191,5 @@ the compiler; the PDF output itself is relatively straight-forward. IDE
functionality is also mostly untested. PDF and IDE testing should be added in functionality is also mostly untested. PDF and IDE testing should be added in
the future. the future.
[docs]: https://typst.app/docs/
[`comemo`]: https://github.com/typst/comemo/ [`comemo`]: https://github.com/typst/comemo/