diff --git a/README.md b/README.md index 2b65c9f..61450ea 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +![BurritOS Logo](assets/logo/logo_full.png) + # BurritOS BurritOS (BurritOS Using Rust Really Improves The Operating System) is an educational operating system written in Rust and running on a RISC-V emulator. It aims to be used as an educational platform for learning about operating systems. diff --git a/assets/logo/README.md b/assets/logo/README.md new file mode 100644 index 0000000..151d836 --- /dev/null +++ b/assets/logo/README.md @@ -0,0 +1,104 @@ +# BurritOS logo + +Designed with Inkscape. +Font: [Fira Code](https://github.com/tonsky/FiraCode) by The Fira Code contributors + +Logo by François AUTIN + +## Licences + +### Fira Code + +Copyright (c) 2014, The Fira Code Project Authors (https://github.com/tonsky/FiraCode) + +This Font Software is licensed under the SIL Open Font License, Version 1.1. +This license is copied below, and is also available with a FAQ at: +http://scripts.sil.org/OFL + + +----------------------------------------------------------- +SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007 +----------------------------------------------------------- + +PREAMBLE +The goals of the Open Font License (OFL) are to stimulate worldwide +development of collaborative font projects, to support the font creation +efforts of academic and linguistic communities, and to provide a free and +open framework in which fonts may be shared and improved in partnership +with others. + +The OFL allows the licensed fonts to be used, studied, modified and +redistributed freely as long as they are not sold by themselves. The +fonts, including any derivative works, can be bundled, embedded, +redistributed and/or sold with any software provided that any reserved +names are not used by derivative works. The fonts and derivatives, +however, cannot be released under any other type of license. The +requirement for fonts to remain under this license does not apply +to any document created using the fonts or their derivatives. + +DEFINITIONS +"Font Software" refers to the set of files released by the Copyright +Holder(s) under this license and clearly marked as such. This may +include source files, build scripts and documentation. + +"Reserved Font Name" refers to any names specified as such after the +copyright statement(s). + +"Original Version" refers to the collection of Font Software components as +distributed by the Copyright Holder(s). + +"Modified Version" refers to any derivative made by adding to, deleting, +or substituting -- in part or in whole -- any of the components of the +Original Version, by changing formats or by porting the Font Software to a +new environment. + +"Author" refers to any designer, engineer, programmer, technical +writer or other person who contributed to the Font Software. + +PERMISSION & CONDITIONS +Permission is hereby granted, free of charge, to any person obtaining +a copy of the Font Software, to use, study, copy, merge, embed, modify, +redistribute, and sell modified and unmodified copies of the Font +Software, subject to the following conditions: + +1) Neither the Font Software nor any of its individual components, +in Original or Modified Versions, may be sold by itself. + +2) Original or Modified Versions of the Font Software may be bundled, +redistributed and/or sold with any software, provided that each copy +contains the above copyright notice and this license. These can be +included either as stand-alone text files, human-readable headers or +in the appropriate machine-readable metadata fields within text or +binary files as long as those fields can be easily viewed by the user. + +3) No Modified Version of the Font Software may use the Reserved Font +Name(s) unless explicit written permission is granted by the corresponding +Copyright Holder. This restriction only applies to the primary font name as +presented to the users. + +4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font +Software shall not be used to promote, endorse or advertise any +Modified Version, except to acknowledge the contribution(s) of the +Copyright Holder(s) and the Author(s) or with their explicit written +permission. + +5) The Font Software, modified or unmodified, in part or in whole, +must be distributed entirely under this license, and must not be +distributed under any other license. The requirement for fonts to +remain under this license does not apply to any document created +using the Font Software. + +TERMINATION +This license becomes null and void if any of the above conditions are +not met. + +DISCLAIMER +THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT +OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE +COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL +DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM +OTHER DEALINGS IN THE FONT SOFTWARE. diff --git a/assets/logo/logo.png b/assets/logo/logo.png new file mode 100644 index 0000000..15c8513 Binary files /dev/null and b/assets/logo/logo.png differ diff --git a/assets/logo/logo.svg b/assets/logo/logo.svg new file mode 100644 index 0000000..91ac653 --- /dev/null +++ b/assets/logo/logo.svg @@ -0,0 +1,377 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Background of the logo + Background circle + + + diff --git a/assets/logo/logo_128.png b/assets/logo/logo_128.png new file mode 100644 index 0000000..1518e3a Binary files /dev/null and b/assets/logo/logo_128.png differ diff --git a/assets/logo/logo_full.png b/assets/logo/logo_full.png new file mode 100644 index 0000000..fcd2c69 Binary files /dev/null and b/assets/logo/logo_full.png differ diff --git a/assets/logo/logo_full.svg b/assets/logo/logo_full.svg new file mode 100644 index 0000000..7730f6e --- /dev/null +++ b/assets/logo/logo_full.svg @@ -0,0 +1,5986 @@ + + + +BurritS diff --git a/doc/DOCUMENTATION.md b/doc/DOCUMENTATION.md new file mode 100644 index 0000000..81c15e1 --- /dev/null +++ b/doc/DOCUMENTATION.md @@ -0,0 +1,196 @@ +# Comment utiliser la documentation Rust + +![](https://www.rust-lang.org/static/images/rust-social-wide.jpg) + +## Écrire un commentaire en Rust + +Pour écrire un commentaire qui apparaitra sur la doc de cargo, écrivez : + +```rust +/// Votre commentaire +``` +pour commenter votre fonction, attribut, structure, module.... + +Pour les commentaires de **crate**, utilisez : + +```rust +//! Votre commentaire +``` + +*Les commentaires style java (`/** */`) sont supporté à l'exception des règles `@` **mais utilisez plutôt les commentaires standard de rust please***. + +Vous pouvez ensuite écrire votre commentaire comme bon vous semble; la documentation supporte le markdown, n'hésitez surtout pas à mettre des h3, des textes den gras, des exemple encapsulé, etc. + +Petit aide avec la markdown dans le chapitre [#aide-markdown](#aide-markdown). + + +### Exemple + +Vous obtenez quelque chose sur votre code comme à la figure 1. + +![Capture d'écran de main.rs](Screenshot_20221019_153737.png "Aperçu du main") + + +## Générer la documentation Rust + +Éxecutez la commande __`cargo doc`__ dans le dossier du projet, cela va générer un dossier dans le dossier **target/doc/** qui contient des pages web, ouvrez le fichier **target/doc/burritos/all.html**. + +Lors de l'affichage de la liste de vos fonctions et autres éléments, la doc **n'affiche que la première ligne**, le autres lignes sont affiché lorsqu'on ouvre les détails. + +### Exemple + +En partant du code de la figure 1, vous obtenez une documentation comme aux figures 2 et 3. + +!["Page d'accueil de la doc"](Screenshot_20221019_153803.png "Page all.html de la crate burritos généré à partir de l'exemple de la figure 1") + +!["Page de la fonction main de la doc"](Screenshot_20221019_153817.png "Page de la fonction main") + + +## Aide markdown + +Comme le markdown est utile pour écrire et mettre en page des commentaire en Rust, petit tuto sur comment formaté du texte en markdown. + +lorsque vous voulez passer à la ligne, faites 2 sauts à la ligne en markdown (oui pas une blague), un saut à la ligne sur le fichier markdown n'est pas +considérer comme un passage à la ligne, ça vous permet juste d'écrire des commentaires sans aller trop à droite dans votre IDE comme celui-ci. + +### Italic et gras + +```md +*Texte en italic* _Texte en italic_ + +**Texte en gras** __Texte en gras__ + +***Texte en italic et gras*** + +``` + + +### Titre et sous-titres + +```md +# Titre type h1 + +## Titre type h2 + +etc. jusqu'à + +###### Titre type h6 +``` + +### Listes + +```md +- Une +- Liste +- Non +- Ordonnée + +1. Une +2. Liste +3. Ordonnée + +- [x] Liste +- [ ] de +- [ ] tâches +``` + +#### Exemple + +- Une +- Liste +- Non +- Ordonnée + +1. Une +2. Liste +3. Ordonnée + +- [x] Liste +- [ ] de +- [ ] tâches + + +### Code + +```md + `Commentaire mono-ligne` +``` + +```md + ``` + Commentaire + Multi + ligne + ``` +``` + +```md + ```md + Commentaire + multi + ligne + avec + coloration + syntaxique (ici md pour markdown) + ``` +``` + +#### Exemple + + +Texte avant `Commentaire mono-ligne` texte après + +``` +Commentaire +multi +ligne +``` + +### Tableaux + +```md + +| Colonne 1 | Colonne 2 | +|-----------|-----------| +| ligne 1 | ligne 1 | +| ligne 2 | ligne 2 | + +``` + +#### Exemple + +| Colonne 1 | Colonne 2 | +|-----------|-----------| +| ligne 1 | ligne 1 | +| ligne 2 | ligne 2 | + +### Liens et images + +```md +[Mon lien](www.google.com) +![Mon image sur internet](www.imagelink.com/image.png) +![Mon image stocké sur mon pc](image/monscreenshot.png) +``` + + +## Faire des tests + +Pour écrire vos tests faites comme dans l'exemple ci-dessous: + +![Exemple de test](Screenshot_20221019_173551.png) + +Executez ensuite les tests en faisant `cargo test`, vous obtenez comme en suivant l'exemple ci-dessus le résultat de la figure 5. + +![Exemple de résultat des tests](Screenshot_20221019_174036.png) + +Lors d'un cargo build optimisé (`cargo build --release`), les tests ne sont pas inclus dans le fichier binaire. + +## Liens utiles + +La documentation officielle du crate core: [https://doc.rust-lang.org/core/index.html](https://doc.rust-lang.org/core/index.html) + +La documentation officielle du crate std: [https://doc.rust-lang.org/std/index.html](https://doc.rust-lang.org/std/index.html) + +La documentation des crates téléchargeable sur [https://crates.io/](https://crates.io/) est retrouvable sur: [https://docs.rs/](https://docs.rs/) + +Pour le markdown vous pouvez retrouver des tutos ici: [https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html](https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html) et ici [https://www.markdownguide.org/cheat-sheet/](https://www.markdownguide.org/cheat-sheet/) diff --git a/doc/Screenshot_20221019_153737.png b/doc/Screenshot_20221019_153737.png new file mode 100644 index 0000000..f407abb Binary files /dev/null and b/doc/Screenshot_20221019_153737.png differ diff --git a/doc/Screenshot_20221019_153803.png b/doc/Screenshot_20221019_153803.png new file mode 100644 index 0000000..8e7f3f7 Binary files /dev/null and b/doc/Screenshot_20221019_153803.png differ diff --git a/doc/Screenshot_20221019_153817.png b/doc/Screenshot_20221019_153817.png new file mode 100644 index 0000000..456a514 Binary files /dev/null and b/doc/Screenshot_20221019_153817.png differ diff --git a/doc/Screenshot_20221019_173551.png b/doc/Screenshot_20221019_173551.png new file mode 100644 index 0000000..463f662 Binary files /dev/null and b/doc/Screenshot_20221019_173551.png differ diff --git a/doc/Screenshot_20221019_174036.png b/doc/Screenshot_20221019_174036.png new file mode 100644 index 0000000..d404f4a Binary files /dev/null and b/doc/Screenshot_20221019_174036.png differ