Contributing - kleineluka/burial GitHub Wiki
Table of Contents
- Getting Started 🛸
- Code Structure and Format 🍦
- Advice for Development 🥨
- Design Insights 💅
- 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.
- Make sure you have Rust and NodeJS installed on your system.
- Clone the Github repository with
git clone https://github.com/kleineluka/burial
in your terminal. - You now have two options. To easily set everything up, please run
npm run dev
. - You can now run
npm run test
to launch Burial.
Optionally, to now manually set up the development environment, please:
- Navigate to the cloned repistory (ex.
cd burial
) and install all Node packages withnpm install
. - Navigate to the back-end directory (ex.
cd src-backend
) and install all Rust crates withcargo build
. - Now, from the main directory (ex.
cd ..
) you can runnpm 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:
- Find the HTML page in
src/sub/resources/encryption.html
. - Find the Javascript and CSS in
src/sub/resources/assets/js/encryption.js
andsrc/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:
- Find the corresponding Tauri commands in
src-backend/src/resources/encryption.rs
. - 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 toyourpage.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!