The Cairo Programming Language Book, a comprehensive documentation of the Cairo 1 programming language.
English | ็ฎไฝไธญๆ
This repository contains the source of "The Cairo Programming Language" book, a comprehensive documentation of the Cairo 1 programming language. This documentation is your go-to resource for mastering Cairo, created and maintained by the Starknet community. You can read the book online.
Rust related packages:
cargo install mdbook mdbook-i18n-helpers mdbook-last-changed
Host machine packages:
Install gettext for translations, usually available with regular package manager: sudo apt install gettext
.
Install mdbook-quiz-cairo following the instructions here to be able to add interactive quizzes.
Clone this repository.
Install mdbook-cairo for Cairo code blocks
cargo install --path mdbook-cairo
All the Markdown files MUST be edited in english. To work locally in english:
Start a local server with mdbook serve
and visit localhost:3000 to view the book.
You can use the --open
flag to open the browser automatically: mdbook serve --open
.
Make changes to the book and refresh the browser to see the changes.
Open a PR with your changes.
This book is targeting international audience, and aims at being gradually translated in several languages.
All files in the src
directory MUST be written in english. This ensures that all the translation files can be
auto-generated and updated by translators.
To work with translations, these are the steps to update the translated content:
Run a local server for the language you want to edit: ./translations.sh es
for instance. If no language is provided, the script will only extract translations from english.
Open the translation file you are interested in po/es.po
for instance. You can also use editors like poedit to help you on this task.
When you are done, you should only have changes into the po/xx.po
file. Commit them and open a PR.
The PR must start with i18n
to let the maintainers know that the PR is only changing translation.
The translation work is inspired from Comprehensive Rust repository.
If you wish to initiate a new translation for your language without running a local server, consider the following tips:
./translations.sh new xx
(replace xx
with your language code). This method can generate the xx.po
file of your language for you.xx.po
file, execute the command ./translations.sh xx
(replace xx
with your language code), as mentioned in the previous chapter.xx.po
file already exists (which means you are not initiating a new translation), you should not run this command.The cairo-listings
tool is designed to wrap all cairo and starknet plugins for quickly verifying cairo programs. You can verify that listings are correct with the verify
argument, and generate the corresponding output with the output
argument.
Firstly, you need to have scarb
resolved in your path:
They should be available after installing cairo, see here for more details.
To run the cairo-listings
helper tool, ensure that you are at the root of the repository (same directory of this README.md
file), and run:
cargo run --bin cairo-listings
Alternatively, you can also install the tool with:
cargo install --path cairo-listings
The tool scans for all *.cairo
files in the specified directory and performs the following actions:
For a Starknet contract:
scarb build
scarb test
Cairo program:
main
function: scarb cairo-run --available-gas=200000000
scarb build
scarb test
scarb fmt -c
To specify which tests to run, you can add a comment at the top of your file with the following format:
// TAG: <tag1>
// TAGS: <tag1>, <tag2>
Here is a list of available tags:
does_not_compile
: don't run scarb build
does_not_run
: don't run scarb cairo-run --available-gas=200000000
ignore_fmt
: don't run scarb fmt
tests_fail
: don't run scarb test
You can skip and ignore a specific test by adding the corresponding flag:
$ cairo-listings --help
Usage: cairo-listings [OPTIONS]
Options:
-p, --path <PATH> The path to explore for *.cairo files [default: ./listings]
-v, --verbose Print more information
-q, --quiet Only print final results
-f, --formats-skip Skip cairo-format checks
-s, --starknet-skip Skip starknet-compile checks
-c, --compile-skip Skip cairo-compile checks
-r, --run-skip Skip cairo-run checks
-t, --test-skip Skip cairo-test checks
--file <FILE> Specify file to check
-h, --help Print help
-V, --version Print version
In CI, it's preferable to reduce output, so run cairo-listings
with the --quiet
flag.
The mdbook-cairo is a mdbook preprocessor that only removes the // TAG
lines in code blocks.