Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

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.

Awesome Lists containing this project

README 

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






  

[![All Contributors](https://img.shields.io/badge/all_contributors-42-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 to process references and labels, and custom tags.

   ```

   cargo install --path mdbook-cairo

   ```



### Guidelines



Read the [CONTRIBUTING.md](./CONTRIBUTING.md) file for more details on the style guide and guidelines for contributions to the book.



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



### Verifying your Cairo Programs



The `cairo-listings` CLI 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.

Install this tool with:



#### Setup



Firstly, you need to have `scarb` resolved in your path. See [here][installation] for more details.



To run the `cairo-listings` helper tool and verify Cairo programs, 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 verify

```



Alternatively, you can also install the tool with:



```sh

cargo install --path cairo-listings

```



and then run:



```sh

cairo-listings verify

```



[installation]: ./src/ch01-01-installation.md



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



```cairo

// 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`



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

    

    

      Nenad Misiฤ‡
Nenad Misiฤ‡
๐Ÿ“– ๐Ÿ’ป

      Teddy Not Bear
Teddy Not Bear
๐Ÿ“–

      Malatrax
Malatrax
๐Ÿ“– ๐Ÿ’ป

      Beeyoung
Beeyoung
๐Ÿ“– ๐Ÿ’ป

      Charlotte
Charlotte
๐Ÿ“– ๐Ÿ’ป

      Oba
Oba
๐Ÿ“–

      martin machiebe
martin machiebe
๐Ÿ“–

    

    

      Jean-Michel
Jean-Michel
๐Ÿ“– ๐Ÿ’ป

      Emmanuel A Akalo
Emmanuel A Akalo
๐Ÿ“– ๐Ÿ’ป

      Supreme Labs
Supreme Labs
๐Ÿ“– ๐Ÿ’ป

      blocksorcerer
blocksorcerer
๐Ÿ“– ๐Ÿ’ป

      quentin-abei
quentin-abei
๐Ÿ“– ๐Ÿ’ป

      0xjarix
0xjarix
๐Ÿ“–

      kkawula
kkawula
๐Ÿ“– ๐Ÿ’ป