Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/cairo-book/cairo-book

The Cairo Programming Language Book, a comprehensive documentation of the Cairo 1 programming language.
https://github.com/cairo-book/cairo-book

cairo cairo-lang documentation

Last synced: about 2 months ago
JSON representation

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

Lists

README 

        
English | [็ฎ€ไฝ“ไธญๆ–‡](translations/README-cn.md)






  



[![All Contributors](https://img.shields.io/badge/all_contributors-28-orange.svg?style=flat-square)](#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](https://book.cairo-lang.org/).





  
 Created by builders, for builders ๐Ÿ“œ





## Contribute



### Setup



1. Rust related packages:

   - Install toolchain providing `cargo` using [rustup](https://rustup.rs/).

   - Install [mdBook](https://rust-lang.github.io/mdBook/guide/installation.html) and the required extensions:

   ```

   cargo install mdbook mdbook-i18n-helpers mdbook-last-changed

   ```

2. Host machine packages:



   - Install [gettext](https://www.gnu.org/software/gettext/) for translations, usually available with regular package manager: `sudo apt install gettext`.

   - Install [mdbook-quiz-cairo](https://github.com/cairo-book/mdbook-quiz-cairo?tab=readme-ov-file) following the instructions [here](https://github.com/cairo-book/mdbook-quiz-cairo?tab=readme-ov-file#installation) to be able to add interactive quizzes.



3. Clone this repository.



4. Install mdbook-cairo [for Cairo code blocks](#work-locally-cairo-programs-verification)

   ```

   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](http://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 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](https://poedit.net/) 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](https://github.com/google/comprehensive-rust/blob/main/TRANSLATIONS.md).



#### 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-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.



#### Setup



Firstly, you need to have `scarb` resolved in your path:



They should be available after installing cairo, see [here](https://cairo-book.github.io/ch01-01-installation.html) 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:



```sh

cargo run --bin cairo-listings

```



Alternatively, you can also install the tool with:



```sh

cargo install --path cairo-listings

```



#### Usage



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



For a Starknet contract:



- `scarb build`

- If it has tests: `scarb test`



Cairo program:



- If it has a `main` function: `scarb cairo-run --available-gas=200000000`

- Else, `scarb build`

- If it has tests: `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:



```rust

// TAG: 

// TAGS: , 

```



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:



```sh

$ cairo-listings --help



Usage: cairo-listings [OPTIONS]



Options:

  -p, --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     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.



## 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
๐Ÿ’ป

      Tristan
Tristan
๐Ÿ’ป ๐Ÿšง ๐Ÿ‘€

      okhai.stark ( Tony Stark )
okhai.stark ( Tony Stark )
๐Ÿ’ป

      shwang
shwang
๐Ÿ’ป

      kwkr
kwkr
๐Ÿ’ป

      ArnaudBD
ArnaudBD
๐Ÿ’ป

    

    

      Jimmy Fate
Jimmy Fate
๐Ÿ’ป

      SimplementeCao
SimplementeCao
๐Ÿ’ป

      Lucas @ StarkWare
Lucas @ StarkWare
๐Ÿ’ป

      Rรฉmy Baranx
Rรฉmy Baranx
๐Ÿ’ป

      Steven Cordero
Steven Cordero
๐Ÿ“–

      Symmaque
Symmaque
๐Ÿ“– ๐Ÿ’ป

      Asher
Asher
๐Ÿ’ป