Merge pull request #118 from algosup/documents

Merge Documents to main
algosup · Feb 23, 2024 · dd22d8c · dd22d8c
2 parents 0d4b173 + 0b4e448
commit dd22d8c
Show file tree

Hide file tree

Showing 14 changed files with 1,044 additions and 57 deletions.
diff --git a/README.md b/README.md
@@ -1,54 +1,118 @@
 # [2024] - IAT2️⃣
 
-<div style="text-align:center">
+
+<div align="center">
     <a target="_blank" href="https://en.wikipedia.org/wiki/Vierzon">
         <img src="https://img.shields.io/badge/Made%20in-Vierzon-success.svg" alt="Made in Vierzon">
     </a>
     <a target="_blank" href="https://algosup.com/">
         <img src="https://img.shields.io/badge/Made%20at-ALGOSUP-blue.svg" alt="Made at ALGOSUP">
     </a>
-    <div>
-        <img style="width:200px" src="documents\images\IAT2\png\iat2_logo_256px.png" alt="Assembly Team 2">
-    </div>
 </div>
+<div align="center">
+
+  <img style="width:200px; display: block; margin: auto;"  src="documents\images\IAT2\png\iat2_logo_256px.png" alt="Assembly Team 2">
+
+</div>
+
 
 
 ## 🫂 Who are we ?
 | **Picture**                                                                                      | **Name**               | **Role**          | **GitHub**                                                                                                                                                                                                                                                                                                                               | **LinkedIn**                                                                                                                                             |
 | ------------------------------------------------------------------------------------------------ | ---------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------|
-| <img src=https://ca.slack-edge.com/T06AELBCZSB-U06AS9UQZ6Z-g7986289d5c2-512 style="width:200px"> | **Mathias GAGNEPAIN**  | Project Manager   | <a href="https://github.com/MathiasGagnepain">  <picture><source media="(prefers-color-scheme: dark)" srcset="documents/images/management/github_light_logo.png"><source media="(prefers-color-scheme: light)" srcset="documents/images/management/github_dark_logo.png"><img alt="GitHub Logo"  style="width:50px;max-width:50%">    </picture></a>   | [<img src="documents/images/management/linkedin_logo.png" alt="LinkedIn" style="width:50px">](https://www.linkedin.com/in/mathias-gagnepain-426a131b0/)  |  
-| <img src=https://ca.slack-edge.com/T06AELBCZSB-U06BJ1BQE00-g3ffdd245b21-512 style="width:200px"> | **Guillaume DESPAUX**  | Program Manager   | <a href="https://github.com/GuillaumeDespaux">  <picture><source media="(prefers-color-scheme: dark)" srcset="documents/images/management/github_light_logo.png"><source media="(prefers-color-scheme: light)" srcset="documents/images/management/github_dark_logo.png"><img alt="GitHub Logo"  style="width:50px;max-width:50%">    </picture></a>   | [<img src="documents/images/management/linkedin_logo.png" alt="LinkedIn" style="width:50px">](https://www.linkedin.com/in/guillaume-despaux-084b10206/)  |              
-| <img src=https://ca.slack-edge.com/T06AELBCZSB-U06ATEC5AG5-g70bf9de2131-512 style="width:200px"> | **Guillaume DERAMCHI** | Technical Leader  | <a href="https://github.com/Guillaume18100">    <picture><source media="(prefers-color-scheme: dark)" srcset="documents/images/management/github_light_logo.png"><source media="(prefers-color-scheme: light)" srcset="documents/images/management/github_dark_logo.png"><img alt="GitHub Logo"  style="width:50px;max-width:50%">    </picture></a>   | [<img src="documents/images/management/linkedin_logo.png" alt="LinkedIn" style="width:50px">](https://www.linkedin.com/in/guillaume-deramchi-a45116293/) |              
-| <img src=https://ca.slack-edge.com/T06AELBCZSB-U06AXL3CDGC-gf21fde06b1f-512 style="width:200px"> | **Maxime CARON**       | Software Engineer | <a href="https://github.com/MaximeAlgosup">     <picture><source media="(prefers-color-scheme: dark)" srcset="documents/images/management/github_light_logo.png"><source media="(prefers-color-scheme: light)" srcset="documents/images/management/github_dark_logo.png"><img alt="GitHub Logo"  style="width:50px;max-width:50%">    </picture></a>   | [<img src="documents/images/management/linkedin_logo.png" alt="LinkedIn" style="width:50px">](https://www.linkedin.com/in/maxime-caron-dev/)             |              
-| <img src=https://ca.slack-edge.com/T06AELBCZSB-U06CFLBV3MZ-g3621cbd420c-512 style="width:200px"> | **Paul NOWAK**         | Software Engineer | <a href="https://github.com/PaulNowak36">       <picture><source media="(prefers-color-scheme: dark)" srcset="documents/images/management/github_light_logo.png"><source media="(prefers-color-scheme: light)" srcset="documents/images/management/github_dark_logo.png"><img alt="GitHub Logo"  style="width:50px;max-width:50%">    </picture></a>   | [<img src="documents/images/management/linkedin_logo.png" alt="LinkedIn" style="width:50px">](https://www.linkedin.com/in/paul-nowak-0757a61a7/)         |              
-| <img src=https://ca.slack-edge.com/T06AELBCZSB-U06ANSN526S-g20f42d2a13d-512 style="width:200px"> | **Enzo GUILLOUCHE**    | Quality Assurance | <a href="https://github.com/EnzoGuillouche">    <picture><source media="(prefers-color-scheme: dark)" srcset="documents/images/management/github_light_logo.png"><source media="(prefers-color-scheme: light)" srcset="documents/images/management/github_dark_logo.png"><img alt="GitHub Logo"  style="width:50px;max-width:50%">    </picture></a>   | [<img src="documents/images/management/linkedin_logo.png" alt="LinkedIn" style="width:50px">](https://www.linkedin.com/in/enzo-g-b62114293/)             |                 
-
+| <img src=https://ca.slack-edge.com/T06AELBCZSB-U06AS9UQZ6Z-g7986289d5c2-512 style="width:200px"> | **Mathias GAGNEPAIN**  | Project Manager   | <a href="https://github.com/MathiasGagnepain">  <picture><source media="(prefers-color-scheme: dark)" srcset="documents/images/management/github_light_logo.png"><source media="(prefers-color-scheme: light)" srcset="documents/images/management/github_dark_logo.png"><img alt="GitHub Logo"  style="width:50px">    </picture></a>   | [<img src="documents/images/management/linkedin_logo.png" alt="LinkedIn" style="width:50px">](https://www.linkedin.com/in/mathias-gagnepain-426a131b0/)  |  
+| <img src=https://ca.slack-edge.com/T06AELBCZSB-U06BJ1BQE00-g3ffdd245b21-512 style="width:200px"> | **Guillaume DESPAUX**  | Program Manager   | <a href="https://github.com/GuillaumeDespaux">  <picture><source media="(prefers-color-scheme: dark)" srcset="documents/images/management/github_light_logo.png"><source media="(prefers-color-scheme: light)" srcset="documents/images/management/github_dark_logo.png"><img alt="GitHub Logo"  style="width:50px">    </picture></a>   | [<img src="documents/images/management/linkedin_logo.png" alt="LinkedIn" style="width:50px">](https://www.linkedin.com/in/guillaume-despaux-084b10206/)  |              
+| <img src=https://ca.slack-edge.com/T06AELBCZSB-U06ATEC5AG5-g70bf9de2131-512 style="width:200px"> | **Guillaume DERAMCHI** | Technical Leader  | <a href="https://github.com/Guillaume18100">    <picture><source media="(prefers-color-scheme: dark)" srcset="documents/images/management/github_light_logo.png"><source media="(prefers-color-scheme: light)" srcset="documents/images/management/github_dark_logo.png"><img alt="GitHub Logo"  style="width:50px">    </picture></a>   | [<img src="documents/images/management/linkedin_logo.png" alt="LinkedIn" style="width:50px">](https://www.linkedin.com/in/guillaume-deramchi-a45116293/) |              
+| <img src=https://ca.slack-edge.com/T06AELBCZSB-U06AXL3CDGC-gf21fde06b1f-512 style="width:200px"> | **Maxime CARON**       | Software Engineer | <a href="https://github.com/MaximeAlgosup">     <picture><source media="(prefers-color-scheme: dark)" srcset="documents/images/management/github_light_logo.png"><source media="(prefers-color-scheme: light)" srcset="documents/images/management/github_dark_logo.png"><img alt="GitHub Logo"  style="width:50px">    </picture></a>   | [<img src="documents/images/management/linkedin_logo.png" alt="LinkedIn" style="width:50px">](https://www.linkedin.com/in/maxime-caron-dev/)             |              
+| <img src=https://ca.slack-edge.com/T06AELBCZSB-U06CFLBV3MZ-g3621cbd420c-512 style="width:200px"> | **Paul NOWAK**         | Software Engineer | <a href="https://github.com/PaulNowak36">       <picture><source media="(prefers-color-scheme: dark)" srcset="documents/images/management/github_light_logo.png"><source media="(prefers-color-scheme: light)" srcset="documents/images/management/github_dark_logo.png"><img alt="GitHub Logo"  style="width:50px">    </picture></a>   | [<img src="documents/images/management/linkedin_logo.png" alt="LinkedIn" style="width:50px">](https://www.linkedin.com/in/paul-nowak-0757a61a7/)         |              
+| <img src=https://ca.slack-edge.com/T06AELBCZSB-U06ANSN526S-g20f42d2a13d-512 style="width:200px"> | **Enzo GUILLOUCHE**    | Quality Assurance | <a href="https://github.com/EnzoGuillouche">    <picture><source media="(prefers-color-scheme: dark)" srcset="documents/images/management/github_light_logo.png"><source media="(prefers-color-scheme: light)" srcset="documents/images/management/github_dark_logo.png"><img alt="GitHub Logo"  style="width:50px">    </picture></a>   | [<img src="documents/images/management/linkedin_logo.png" alt="LinkedIn" style="width:50px">](https://www.linkedin.com/in/enzo-g-b62114293/)             |                 
+
+Read the list of [contributors](https://github.com/algosup/2023-2024-project-3-virtual-processor-team-2/contributors) to see who helped with the project!
 <hr>
 
 ## 📚 What is this project ?
 
-This project involves the creation of a new assembly language for enhanced understanding and usability, we introduce the AT2, accompanied by its dedicated assembler (IAT2).
+This project (IAT2) involves the creation of a new assembly language for enhanced understanding and usability, we introduce the AT2, accompanied by its dedicated assembler (2AT2) and virtual Processor (VAT2).
 
 ## 🕵️‍♂️ What is AT2 ?
 
 AT2 stands for **A**ssembly **T**eam **2**, representing our proprietary assembly language.
+*You can also refer to the [documentation](./documents/functional/at2_language_documentation.pdf).*
 
-## 💻 What is 2AT2 ?
+## ⚙️ What is 2AT2 ?
 
-2AT2 stands for **A**Assembler for **A**ssembly **T**eam **2**, serving as the exclusive assembler capable of reading and convert `.aop` files written in our AT2 language into machine code (Binary).
+2AT2 stands for **A**ssembler for **A**ssembly **T**eam **2**, serving as the exclusive assembler capable of reading and converting `.aop` files written in our AT2 language into machine code (Binary).
 
-## 💾 Why we choose .aop as extension ?
+## 💻 What is VAT2 ?
+
+VAT2 stands for **V**irtual Processor for **A**ssembly **T**eam **2**, serving as a virtual processor able to execute our binary generated by 2AT2.
+
+## 📦 What is IAT2 ?
+
+IAT2 stands for **I**ntegral **A**ssembler **T**eam **2**, it's the name of the whole project (2AT2 + VAT2).
+
+## 💾 Why did we choose .aop as extension ?
 
 We selected the `.aop` extension to signify **A**op **O**riginal **P**rogram, embodying an infinite recursive loop inspired by [ZWEI](https://en.wikipedia.org/wiki/EINE_and_ZWEI#Naming)'s name.
 
 ## 🔎 How does it work ?
 
 To assemble your code in `.aop`, here is some commands related to **2AT2** usage.
 
-1. Compile you AT2's code: `2at2`
+1. Compile you AT2's code: `2at2 <path/file.aop>`
 2. Display the commands list: `2at2 -help` or `2at2 -h`
-3. Compile + run your AT2's code with VAT2: `2at2 -run`
+3. Compile + run your AT2's code with VAT2: `iat2 <path/file.aop>`
+
+*You can also refer to the entire [user manual](./documents/functional/user_manual.md) and [AT2 documentation](./documents/functional/at2_language_documentation.pdf).*
+
+### 🔗 Requires
+
+To use IAT2 you need:
+
+- A computer *(Windows Recommended)*
+- GCC installed, you can install it [here](https://www.devdungeon.com/content/install-gcc-compiler-windows-msys2-cc)
+
+### 💽 Installation
+
+Step By Step:
+
+1. Clone the repository: `git clone https://github.com/algosup/2023-2024-project-3-virtual-processor-team-2.git`
+2. Go at the project root
+3. Build the project
+   - How to use with mingw: (Windows)
+     1. Execute ``cmake -S . -B Build -G "MinGW Makefiles"``
+     2. Execute ``cd Build``
+     3. Execute ``mingw32-make``
+   - How to use with msys2: (Windows)
+     1. Execute ``cmake -S . -B Build -G "MSYS Makefiles"``
+     2. Execute ``cd Build``
+     3. Execute ``make``
+
+It will generate a bin folder containing our runners to use it refers to [How does it work](#🔎-how-does-it-work)
+
+*You can also refer to [user manual](./documents/functional/user_manual.md).*
+
+## 🛠️ Made with
+
+* [C99](https://en.wikipedia.org/wiki/C99) - C programming Language[.](https://www.youtube.com/watch?v=tas0O586t80)
+* [C++](https://cplusplus.com/) - C++ Language used for unit tests.
+* [Visual Studio Code](https://code.visualstudio.com/) - [IDE](https://en.wikipedia.org/wiki/Integrated_development_environment) (Integrated Developement Environement).
+* [CMake](https://cmake.org/) - Software Build System for C & C++ code.
+* [GoogleTest](https://github.com/google/googletest) - Google's internal systems for continuous integration.
+* [GCC](https://gcc.gnu.org/) - Used to compile C language.
+* [G++](https://gcc.gnu.org/) - Used to compile C++ language 
+
+## 🤝 Contributing
+
+If you want to contribute please take a look to [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## 🗃️ Versions
+- **Latest :** 1.1.0
+- **Current :** 1.1.0
+- Versions List : [Cliquer pour afficher](https://github.com/algosup/2023-2024-project-3-virtual-processor-team-2/tags)
 
+## ⚖️ License
 
+This project is under license ``MIT`` - see the [LICENSE](LICENSE) file for more information.
 
 <a target="_blank" href="https://algosup.com/"><picture><source media="(prefers-color-scheme: dark)" srcset="documents/images/management/algosup_orange.svg"><source media="(prefers-color-scheme: light)" srcset="documents/images/management/algosup_light_blue.svg"><img alt="ALGOSUP Logo" style="max-width:1440px" >
diff --git a/SECURITY.md b/SECURITY.md
@@ -4,12 +4,19 @@
 
 These versions are currently updated and can include security patches:
 
-| Version | Supported          |
-| ------- | ------------------ |
-| > 0.0.4 | :white_check_mark: |
-| &emsp;0.0.3 | :white_check_mark: |
-| &emsp;0.0.2 | :white_check_mark: |
-| &emsp;0.0.1 | :white_check_mark: |
+| Version     | Supported          |
+| ----------- | ------------------ |
+| > 1.1.0     | :white_check_mark: |
+| &emsp;1.0.0 | :white_check_mark: |
+| &emsp;0.5.0 | :x: |
+| &emsp;0.4.0 | :x: |
+| &emsp;0.3.0 | :x: |
+| &emsp;0.2.0 | :x: |
+| &emsp;0.1.1 | :x: |
+| &emsp;0.0.4 | :x: |
+| &emsp;0.0.3 | :x: |
+| &emsp;0.0.2 | :x: |
+| &emsp;0.0.1 | :x: |
 
 ## Reporting a Vulnerability
 

diff --git a/documents/functional/user_manual.md b/documents/functional/user_manual.md
@@ -0,0 +1,127 @@
+<img src="../images/IAT2/png/iat2_logo_256px.png" alt="IAT2 Logo" style="display: block; margin: auto;">
+
+# User Manual
+
+## Table of Contents
+- [User Manual](#user-manual)
+  - [Table of Contents](#table-of-contents)
+  - [1. Introduction](#1-introduction)
+  - [2. Getting Started](#2-getting-started)
+    - [2.1 Installation](#21-installation)
+  - [3. Execution](#3-execution)
+    - [IAT2](#iat2)
+      - [Assembler](#assembler)
+      - [Virtual Processor](#virtual-processor)
+  - [4. Troubleshooting](#4-troubleshooting)
+    - [4.1 Common Issues](#41-common-issues)
+    - [4.2 FAQs](#42-faqs)
+      - [Can I use negative numbers ?](#can-i-use-negative-numbers-)
+      - [Can I use VAT2 to execute my own binary file ?](#can-i-use-vat2-to-execute-my-own-binary-file-)
+      - [Can I execute 2AT2's binary on real hardware ?](#can-i-execute-2at2s-binary-on-real-hardware-)
+  - [5. Appendix](#5-appendix)
+    - [5.1 Glossary](#51-glossary)
+    - [5.2 AT2 documentation](#52-at2-documentation)
+
+## 1. Introduction
+
+Welcome to the User Manual for [IAT2](#iat2-id). This guide is designed to help you understand and use the features of our product efficiently.
+
+## 2. Getting Started
+
+### 2.1 Installation
+Requirements:
+- Git
+- CMake
+- g++ (latest version)
+- gcc (latest version)
+
+*if you don't have git installed [CLICK HERE TO DOWNLOAD](https://git-scm.com/download/win).*  
+*if you don't have cmake installed [CLICK HERE TO DOWNLOAD](https://cmake.org/download/).*  
+*if you don't have gcc installed [CLICK HERE TO DOWNLOAD](https://www.devdungeon.com/content/install-gcc-compiler-windows-msys2-cc).*  
+*if you don't have msys2 installed [CLICK HERE TO DOWNLOAD](https://www.msys2.org/).*
+
+Follow these steps to install [IAT2](#iat2-id):
+  1. Clone the repository: ``git clone https://github.com/algosup/2023-2024-project-3-virtual-processor-team-2.git``
+  2. Go at the project root
+  3. Create an empty directory named "bin" at the project root
+  4. Go at the project root
+  5. Build the project
+     - How to use with mingw: (Windows)
+       - Execute cmake -S . -B Build -G "MinGW Makefiles"
+       - Execute cd Build
+       - Execute mingw32-make
+     - How to use with msys2: (Windows)
+       - Execute cmake -S . -B Build -G "MSYS Makefiles"
+       - Execute cd Build
+       - Execute make
+     - How to use with make: (Linux)
+       - Execute cmake -S . -B Build
+       - Execute cd Build
+       - Execute make
+
+## 3. Execution
+
+### [IAT2](#iat2-id)
+
+[IAT2](#iat2-id) is planned to compile and execute in a single step, if you want to compile and execute separatly your can refer to [Assembler (Compile)](#assembler) and [Virtual Processor (Execute)](#virtual-processor).
+
+#### Assembler
+| Command | alias | Usage | output |
+|---|---| --- | --- |
+| ``2at2 <path/file.aop> [param]``| | Compile your [.aop](#aop-id) file | binary file |
+| ``2at2 --help`` | ``2at2 -h`` | Display the list of command for [2at2](#2at2-id) | |
+| ``2at2 --version`` | ``2at2 -v`` | Display the version of [2at2](#2at2-id) | |
+| ``2at2 <file> --debug`` | ``2at2 <file> -d`` | Compile the program with the debugger | 2at2.log |
+
+
+#### Virtual Processor
+
+Type: ``vat2`` to run the virtual processor and open the virtual terminal.
+
+*Virtual terminal commands:*
+
+| Command | Usage |
+|---|--- |
+| ``<path/binary_file>``| Execute your binary file |
+| ``help`` |  Display the list of command for [vat2](#vat2-id) |
+| ``clear`` | Clear the terminal |
+| ``version`` | Display the version of [vat2](#vat2-id) |
+| ``exit`` | Close the terminal | 
+
+## 4. Troubleshooting
+
+### 4.1 Common Issues
+
+|Issue | Solution |
+|---|---|
+| Writing on register 3 | Don't write on register 3 |
+
+Your issue is not here ?<br>
+You can also refer to [GitHub Issues](https://github.com/algosup/2023-2024-project-3-virtual-processor-team-2/issues).
+
+### 4.2 FAQs
+
+#### Can I use negative numbers ?
+- **No**, unfortunately negative numbers are not handle yet, but planned for the V2.
+
+#### Can I use [VAT2](#vat2-id) to execute my own binary file ?
+- **Yes and No**, You can only if you use the same binary syntax as [2AT2](#2at2-id).
+
+#### Can I execute [2AT2](#2at2-id)'s binary on real hardware ?
+- **Probably No**, unless you find a real hardware using the same syntax *(If you find it, tell us)*
+
+## 5. Appendix
+
+### 5.1 Glossary
+
+| Name | Definition |
+| --- | --- |
+| <span id="iat2-id">IAT2</span> | Integral Assembler Team 2 (Assembler + Virtual Processor) |
+| <span id="2at2-id">2AT2</span> | Assembler Assembly Team 2 |
+| <span id="vat2-id">VAT2</span> | Virtual processor Assembly Team 2 |
+| <span id="aop-id">.aop</span> | [Aop](#aop-id) Original Program (extension of AT2 language) |
+| <span id="at2-id">AT2</span> | Assembly Team 2 |
+
+### 5.2 [AT2](#at2-id) documentation
+
+You can refer to the [AT2]((#at2-id))'s documentation [HERE](../functional/at2_language_documentation.pdf).