diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index 108d6bf..e43680d 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -1,22 +1,110 @@ # Getting Started -## Linux -- Clone the repository. -- Install Rust using [rustup](https://rustup.rs). -- Open the project folder in [Visual Studio Code](https://code.visualstudio.com). -At this point, there are two options to open a new tunnel. +## Dependencies -### Method 1: Run & Debug -- Install the [CodeLLDB](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb) VS Code extension. -- In VS Code, press F5 to run & debug Burrow.\ -This flow does not work yet (panics). +Before you can start working on Burrow, you'll need to install some dependencies. They are different for each platform: -### Method 2: Cargo -- In VS Code, press Ctrl+\` to open the terminal. -- Type `cargo run`. -- Burrow should open a new tunnel (`Ok("tun0")`), then exit. +
+ Linux -## macOS + 1. Install **rustup** using the instructions on the [website](https://rustup.rs/): + ```bash + $ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + ``` -## Windows + 2. Install **Visual Studio Code** from the [website](https://code.visualstudio.com/#alt-downloads), [Snap Store](https://snapcraft.io/code), or your package manager of choice. +
+ +
+ macOS + + 1. Install **rustup** using the instructions on the [website](https://rustup.rs/): + ```bash + $ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + ``` + + 2. Download and install **Visual Studio Code** from the [website](https://code.visualstudio.com/#alt-downloads), or by using brew: + ``` + brew install --cask visual-studio-code + ``` + + 3. Download and Install **Xcode** from the [App Store](https://apps.apple.com/us/app/xcode/id497799835) or the [Apple Developer](https://developer.apple.com/downloads) website. + +
+ + +
+ Windows + + 1. Download **Visual Studio** community edition from the [website](https://visualstudio.microsoft.com/vs/). Install the components for "Desktop Development with C++" + + 2. Install [**Visual Studio Code**](https://apps.microsoft.com/store/detail/visual-studio-code/XP9KHM4BK9FZ7Q), [**PowerShell**](https://apps.microsoft.com/store/detail/powershell/9MZ1SNWT0N5D) and [**Windows Terminal**](https://apps.microsoft.com/store/detail/windows-terminal/9N0DX20HK701) from the Microsoft Store + + 3. Open Windows Terminal and use [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/) to install **git**, **LLVM** and **rustup**: + ```posh + winget install Git.Git + winget install LLVM.LLVM + winget install Rustlang.Rustup + ``` + + 4. Install Rust using rustup: + ```posh + rustup toolchain install stable-msvc + ``` +
+ +## Building + +1. Clone the repository: +``` +git clone git@github.com:hackclub/burrow.git +``` + +2. Open the `burrow` folder in Visual Studio Code: +``` +code burrow +``` + +3. Install the Visual Studio Code extensions [**rust-analyzer**](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) and [**CodeLLDB**](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb). You should get a suggestion to do this automatically: + + + +4. Compile burrow in Visual Studio Code by selecting `Terminal -> Run Build Task` + +## Running + + +
+ Command Line + + You can run burrow on the command line with cargo: + + ``` + cargo run + ``` + + Cargo will ask for your password because burrow needs permission in order to create a tunnel. +
+ +
+ Visual Studio Code + + You can debug the Rust program inside of Visual Studio using the **Run and Debug** tab. + + **_This does not work fully yet_**. Visual Studio Code does not have a way to debug programs with administrative privileges. +
+ +
+ iOS or macOS + + You can run the Burrow app on iOS or macOS using **Xcode**. + + You will need to be logged in with your Apple ID, and it should be a part of **The Hack Foundation** team: + + + + If your Apple ID is not a part of The Hack Foundation team, ask the Slack channel for assistance. + + You should now be able to run the app by opening `Apple/Burrow.xcodeproj` in Xcode, selecting the **App** scheme and clicking **Run**. +
diff --git a/docs/extensions.png b/docs/extensions.png new file mode 100644 index 0000000..ad94ee4 Binary files /dev/null and b/docs/extensions.png differ diff --git a/docs/xcode.png b/docs/xcode.png new file mode 100644 index 0000000..469ada3 Binary files /dev/null and b/docs/xcode.png differ