Contributing - kleineluka/burial GitHub Wiki

Table of Contents

  1. Getting Started 🛸
  2. Code Structure and Format 🍦
  3. Advice for Development 🥨
  4. Design Insights 💅
  5. Request Features and Report Bugs 🧸

If you are not interested in writing code, please refer to Request Features and Report Bugs!

Getting Started 🛸

The application is primarily broken into two primary parts. First, Rust is used as the back-end (think doing the decryption, modifying files, etc). Second, Tauri is used to bridge the front-end. You can find the back-end in src-backend and the front-end in src. Now, let's get started!

Please note, that these instructions only apply if you want to contribute towards development. Please head to the Releases section if you are simply planning to use the program.

  1. Make sure you have Rust and NodeJS installed on your system.
  2. Clone the Github repository with git clone https://github.com/kleineluka/burial in your terminal.
  3. You now have two options. To easily set everything up, please run npm run dev.
  4. You can now run npm run test to launch Burial.

Optionally, to now manually set up the development environment, please:

  1. Navigate to the cloned repistory (ex. cd burial) and install all Node packages with npm install.
  2. Navigate to the back-end directory (ex. cd src-backend) and install all Rust crates with cargo build.
  3. Now, from the main directory (ex. cd ..) you can run npm run tauri dev to run Burial!

Code Structure and Format 🍦

Upon opening the front-end (src), you will see a few folders alongside index.html and settings.html. assets contains code shared throughout the whole project and in the two html files in the main page, data contains json structures that are read from the front-end from certain features (ex. templates, sifting), and sub contains all of the sub-menus provided in the program (ex. Resources, Reversing, and so on). The structure of each sub-menu is similar to the main src structure without the data and sub directories. If you want to, for example, edit the "Encryption" page - you would do the following:

  1. Find the HTML page in src/sub/resources/encryption.html.
  2. Find the Javascript and CSS in src/sub/resources/assets/js/encryption.js and src/sub/resources/assets/css/encryption.css.

Upon opening the back-end (src-backend), you will want to then navigate to src. You will then see main.rs, settings.rs, and a few folders. Folders like config and utils are used throughout the project and are mostly just public helper functions. Folders like resources, modmanager, and reversing all correspond to their sub-menus in the front-end (for example the code in src-backend/src/resources will be called by the front-end in src/sub/resources). If you want to, for example, edit the code behind the "Encryption" page - you would do the following:

  1. Find the corresponding Tauri commands in src-backend/src/resources/encryption.rs.
  2. Find the helper functions used in src-backend/src/utils/cypher.rs.

Please note that all Rust is typically in snake case and all Javascript is in camel case. Tauri automatically translates between the two. Please make sure that your code is commented as well to make it easier for future contributors!

Advice for Development 🥨

  • Control + Shift + I will open developer tools.
  • If you want to paste in the developer console, you need to type allow pasting first.
  • In your console, you can type __TAURI_INVOKE__("navigate", { page: "yourpage.html" }); to go to yourpage.html via my navigate Tauri command (which you can see inutils/commands.rs).
  • You can build artifacts with npm run build.

Design Insights 💅

A Question: Why are we blocking async functions via tokio instead of converting the main? And, An Answer: This is that may will change as the complexity of Burial increases. By taking ownership of a tokio main thread from Tauri there is more complexity to handle, but better trade-offs like faster loading. However, with a more "naïve" blocking approach, our Javascript can always assume that localstorage is up-to-date and thus always have our links, updates, etc. ready! This means we don't need to register a listener on every page to elegantly fade in the Github icon in the bottom left, for example. Due to the "minimal" benefits (a second or two of loading at start-up), this is something that I'll work towards achieving after core functionality is done.

Bug Reports and Features 🧸

Please just head over to the Github's Issues Page and use one of the templates! I'm excited to hear your feedback!