Skip to content

Developer Setup Guide

Jump to bottom
zacharybonagura edited this page Dec 19, 2024 · 4 revisions

For this setup guide, we will be using Visual Studio Code. You can use other IDEs such as IntelliJ and Eclipse, but we prefer using Visual Studio Code and GitHub Desktop.

Installing Visual Studio Code

Visit the following page to download Visual Studio Code: https://code.visualstudio.com/

Install the application by following the on-screen instructions for your operating system (Windows, macOS, or Linux).

Installing Rust

Once Visual Studio Code has been installed, launch the application and open the Extensions Marketplace on the toolbar on the left-hand side (Ctrl+Shift+X or Cmd+Shift+X on macOS). Search for and install the following extensions:

  1. rust-analyzer (provides advanced Rust language support).
  2. CodeLLDB (for debugging and testing Rust applications).

Next, download and install Rust by visiting the Rust website (https://www.rust-lang.org/tools/install) and following the installation guide for your operating system (Windows, macOS, or Linux). After installation, verify that Rust is installed by opening a terminal and running:

rustc --version

This command will display the installed version of Rust.

Rust comes with Cargo, its package manager and build tool. Verify Cargo installation by running:

cargo --version

Installing Wasm-pack

Wasm-pack is a tool essential for WebAssembly projects. In our case, Aris is just that. To install wasm-pack, open a terminal and run the following command:

cargo install wasm-pack

Installing GitHub Desktop

Visit the following page to download GitHub Desktop: https://desktop.github.com/

To set up GitHub Desktop, follow Parts 1 and 2 of the Getting started with GitHub Desktop guide. Part 3 is about contributing to projects and adding and cloning repositories, but this setup guide will walk you through this process for Aris.

Forking the Repository

Follow these steps to fork the main repository:

  1. Go to the the main Aris repository: https://github.com/Bram-Hub/aris
  2. Press the "Fork" button on the top right side of the page.

Downloading the Project

Once the link to your forked version has been copied, you must clone it onto your computer.

Navigate to your fork, click the green "Code" button, and then click on "Open in GitHub Desktop". After a few moments, GitHub Desktop should open and prompt you to clone the repository. The repository URL should already be filled in and the local path should, by default, be C:\Users\your_username\Documents\GitHub\aris. You can change this local path if you want, but we don't recommend it. Click on the "Clone" button to clone the repository. Click on "Fetch Origin" to fetch from your fork.

The one operation that GitHub Desktop cannot do is syncing your forked repository with the upstream repository. For information on how to do that, please refer to GitHub's tutorial on syncing a fork.

Opening the Project with VSCode

After opening VSCode, click on file in the top-left corner. Then click on the "Open Folder" button. Navigate to C:\Users\your_username\Documents\GitHub\aris (or if you changed the path in the previous step, whatever path you changed it to) and open the folder. After a few moments, VSCode should open the project up. In the Explorer section in the top-left corner, you will find an ARIS tab that contains all the associated files.

Running Aris Locally

To run Aris locally,

  1. First open a terminal and navigate to the Aris project directory. For example:
cd C:\Users\your_username\Documents\GitHub\aris
  1. Verify that wasm-pack is installed by running:
wasm-pack --version

If the version number appears, wasm-pack is installed correctly. If not, install it using:

cargo install wasm-pack
  1. Build the Aris project by using wasm-pack:
wasm-pack build web-app --target web --out-dir static/pkg
  1. Once the build is complete, run the following command to launch a localhost server.
python3 -m http.server --directory web-app/static

Then, open a web browser and go to http://localhost:8000/ to view your version of the project.

Whenever you make changes to the Aris codebase, you must re-execute the previous commands to see the updated results in your local version. While this can be inconvenient, it is necessary. Additionally, you may sometimes find that your changes are not reflected when running the project locally. This issue is often due to your browser's caching behavior.

If you're using Google Chrome, you can solve this by right-clicking anywhere on the page, selecting Inspect, and navigating to the Network tab at the top. In this tab, enable the Disable cache checkbox. Then, reload the page to check for your updates. If the changes still don't appear, try switching to a different browser to load the localhost page, which should display the new updates.

Note: When initially running, your local project may look like this. {918B6579-B6D5-42DC-8802-139536A77758} This is because Aris incorporates integrity attributes in its HTML. The integrity attribute is a security feature used with <link> and <script> elements to ensure that the resource being loaded has not been tampered with. It uses Subresource Integrity (SRI), which provides a cryptographic hash of the file. When the browser loads the resource, it calculates the hash of the fetched file and compares it to the provided hash in the integrity attribute. If the hashes do not match, the browser blocks the resource from being loaded.

If you encounter this issue, simply comment out the integrity attributes, re-execute the commands, and reload the localhost page. Once reloaded, Aris should load properly. However, ensure that you restore the integrity attributes before uploaded your changes to the work directory.

Uploading Changes Live

When you're ready to upload your changes from your local project to the main website, it's important to ensure your code is clean, well-formatted, and builds correctly. Follow these steps to prepare your changes:

  1. Run the following commands in a terminal to update dependencies, format your code, and verify functionality through tests:
cargo update
cargo fmt
cargo clippy
cargo test
  1. Verify that your wasm-pack build works correctly by running:
wasm-pack build web-app --target web --out-dir static/pkg

Once all the checks pass and your project runs as expected, you can push your changes live. Remember: Before pushing your changes live, make sure to restore the integrity attributes in your HTML index file. This is essential for maintaining the security and integrity of the website.

  1. Open GitHub Desktop and commit your changes. Be sure to include a clear commit message summarizing the updates.
  2. Click the Push button to upload your changes to your GitHub repository.
  3. Navigate to your repository on GitHub in your browser. Open a pull request from your branch to the main branch, providing a detailed description of your changes.
  4. Once you submit the pull request, the Aris repository will process the updates and deploy a new version of the website at https://aris.bram-hub.com/.

After a few moments, the website will reflect your changes.

Aris Wiki

Clone this wiki locally