language-servers/gleam
1
0
Fork 0
mirror of https://github.com/gleam-lang/gleam.git synced 2025-12-23 09:47:08 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Start new compiler docs

Browse source
This commit is contained in:
Louis Pilfold 2021-09-21 21:13:09 +01:00
parent ff654c28cc
commit 2d1dbedf70
2 changed files with 31 additions and 61 deletions
Download patch file Download diff file Expand all files Collapse all files

9
CONTRIBUTING.md
View file

@ -79,15 +79,6 @@ docker run -v $(pwd):/opt/app -it -w /opt/app rust:latest bash
Here are some tips and guidelines for writing Rust code in the Gleam compiler:
Never write code that can cause the compiler to panic (`panic!`, `unwrap`,
`expect`) as a compiler panic is confusing to the user. When possible rewrite
the code in a way that makes the error impossible. If that cannot be done and
the error is either common or due to a mistake by the user return an error
value that will be printed with an appropriate helpful error message. If the
error _should_ never happen and its occurrence indicates a fatal compiler bug
the `.expect` method of the `GleamExpect` trait can be used. This is
similar to `.expect` but prints a more helpful error message to the user.
The `GLEAM_LOG` environment variable can be used to cause the compiler to
print more information for debugging and introspection. i.e.
`GLEAM_LOG=trace`.

83
docs/architecture.md → docs/compiler/README.md
View file

@ -1,22 +1,41 @@
# Architecture
# Compiler documentation
This document describes the high-level architecture of the Gleam compiler.
Hello! Welcome to the documentation for the Gleam compiler. I hope you have fun
with the project!
## Overview
On the highest level, a `gleam` binary receives Gleam source code as input
and produces one of its available backend formats:
- Erlang source code.
- JavaScript source code.
There is currently no formal specification of Gleam source, apart from the
There is currently no formal specification of Gleam. See the the
programmer-oriented [Language tour][language-tour] and the [language integration
tests][language-tests].
tests][language-tests] for information on the language itself.
[language-tour]: https://gleam.run/book/tour/index.html
[language-tests]: https://github.com/gleam-lang/gleam/tree/main/test/language
## Project structure
The project is made up of several Rust crates (projects):
- `compiler-core`: This project parses, analyses, and compiles Gleam projects.
It is entirely pure and has no IO so that is provided by the other Rust crates
that wrap this one.
- `compiler-cli`: A command line interface that wraps the core compiler and
provides IO to files and to the console.
- `compiler-wasm`: A JavaScript interface to the core compiler via web assembly.
Suitable for running in a web browser.
In addition to the Rust code there are these components:
- `Makefile`: A makefile that defines shortcut commands for common tasks when
working in the Gleam codebase. Run `make help` to view them.
- `test`: A collection of Gleam projects that serve as integration tests for the
compiler.
- `deny.toml`: Configuration for the `cargo-deny` tool which is used to ensure
that the Rust libraries the compiler depends on adhere to our expectations.
- `containers`: A collection of docker-files used to produce OCI containers for
each Gleam release.
- `.github/workflows`: GitHub Actions workflow definitions, used to build, test,
and release new versions of the project.
- `docs`: You're looking at it pal.
## Compilation flow
The process for compiling Gleam modules within the compiler looks roughly like
@ -61,43 +80,3 @@ this:
Erlang or JavaScript
source code
```
## Code map
This section describes various modules comprising Gleam's core structure.
Pay attention especially to the following sections:
- **Architecture Invariant**: important note about crucial assumptions about the code/behavior
- **API Boundary**: an exposed interface that requires careful design, e.g. because it has internal users to support
### `ast`
Types that serve as the Gleam AST, both in its *untyped* and *typed* form.
Each tree describes a single Gleam module at its root.
Untyped trees contain untyped expressions only.
Typed trees contain typed expressions together with metadata
such as the types of expressions and information on how to generate code for each value constructor used.
Here, code has gained the context necessary to produce final Gleam output.
### `parse`
The parser receives source code for a single Gleam module (as `&str`, as opposed to a stream)
and produces an untyped AST together with `ModuleExtra`
containing various types of comments plus empty lines.
Currently this means that parsing is tightly coupled with the AST structure.
**Architecture Invariant**: parsing may fail, the output is in `Result<T, Error>` form.
**API Boundary**: high-level operations on code, such as formatting, begin here.
### `erl`
TODO
### `javascript`
TODO