Skip to content

The Cairo Programming Language Book, a comprehensive documentation of the Cairo 1 programming language.

License

Notifications You must be signed in to change notification settings

0xEniotna/cairo-book.github.io

 
 

Repository files navigation

All Contributors

The Cairo Programming Language Book

Alexandria

Description

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.

Created by builders, for builders 📜

Contribute

Setup

  1. Rust related packages:

    • Install toolchain providing cargo using rustup.
    • Install mdBook and the translation extension:
    cargo install mdbook mdbook-i18n-helpers
    
  2. Host machine packages:

    • Install gettext for translations, usually available with regular package manager: sudo apt install gettext.
  3. Clone this repository.

  4. Install mdbook-cairo for Cairo code blocks

    cargo install --path mdbook-cairo
    

Work locally (english, main language)

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.

Work locally (translations)

This book is targetting 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, those 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 stars with i18n to let the maintainers know that the PR is only changing translation.

The translation work is inspired from Comprehensive Rust repository.

Initiate a new translation for your language

If you wish to initiate a new translation for your language without running a local server, consider the following tips:

  • Execute the command ./translations.sh new xx (replace xx with your language code). This method can generate the xx.po file of your language for you.
  • To update your xx.po file, execute the command ./translations.sh xx (replace xx with your language code), as mentioned in the previous chapter.
  • If the xx.po file already exists (which means you are not initiating a new translation), you should not run this command.

Work locally (Cairo programs verification)

The cairo-verify tool is designed to wrap all cairo and starknet plugins for quickly verifying cairo programs.

Setup

Firstly, you need to have the following binaries in your path:

  • cairo-compile
  • cairo-run
  • cairo-test
  • cairo-format
  • starknet-compile

They should be available after installing cairo, see here for more details.

To run the cairo-verify 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-verify

Alternatively, you can also install the tool with:

cargo install --path cairo-verify

Usage

The tool scans for all *.cairo files in the specified directory and performs the following actions:

For a Starknet contract:

  • starknet-compile
  • If it has tests: cairo-test --starknet

Cairo program:

  • If it has a main function: cairo-run
  • Else, cairo-compile
  • If it has tests: cairo-test
  • cairo-fmt

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 cairo-compile/starknet-compile
  • does_not_run: don't run cairo-run
  • ignore_fmt: don't run cairo-fmt
  • tests_fail: don't run cairo-test/cairo-test --starknet

You can skip and ignore a specific test by adding the corresponding flag:

$ cairo-verify --help

Usage: cairo-verify [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-verify with the --quiet flag.

The mdbook-cairo is a mdbook preprocessor that only removes the // TAG lines in code blocks.

Contributors

Fricoben
Fricoben

🤔 🔍 📆
Mathieu
Mathieu

🤔 💻 🧑‍🏫 👀 📆
Nadai
Nadai

🌍
glihm
glihm

💻 🔧
Clément Walter
Clément Walter

👀
V.O.T
V.O.T

💻
Pia
Pia

💻 📝
cryptonerdcn
cryptonerdcn

🌍
Argetlames
Argetlames

🌍
julio4
julio4

💻 🔧
Haresh Gedia
Haresh Gedia

📖
Darlington Nnam
Darlington Nnam

💻
Tiago Neto
Tiago Neto

👀
omahs
omahs

💻
Shramee Srivastav
Shramee Srivastav

💻
Daniel Bejarano
Daniel Bejarano

💻

About

The Cairo Programming Language Book, a comprehensive documentation of the Cairo 1 programming language.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Cairo 43.8%
  • CSS 17.1%
  • JavaScript 16.1%
  • Rust 11.1%
  • Handlebars 10.7%
  • Shell 1.2%