Kieron Morris
632c3fa66b
- `VirtualBox-Wrapper.ps1` now takes 'up' or 'down' as opposed to a machine name. This allows start/stop of a virtualmachine. - `VirtualBox-Wrapper.ps1` now relies on a gitignored `localenv.json` to work. - `VirtualBox-Wrapper.ps1` can also optionally monitor the log file generated from the serial adapter in VirtualBox. - `readme.md` updated to provide instructions on how to populate the `localenv.json` file. - `tasks.json` updated to have a "Clean" task to --remove-orphans, the Build task depends on this. - `tasks.json` updated to have a "Close VirtualBox" task, this runs the `virtualbox-wrapper.ps1` in 'down' mode. The Build task depends on this. - `launch.json` updated to run the `VirtualBox-Wrapper.ps1` with the "-Command up" argument, instead of machine name. - .gitignore updated to ignore any instances of `localenv.json`.
79 lines
4.0 KiB
Markdown
79 lines
4.0 KiB
Markdown
# Asuro
|
|
|
|
We welcome everyone to give building/breaking/fixing/shooting Asuro a go, feel free to follow the steps below and mess with Asuro for fun or profit.
|
|
|
|
## Setting up your build environment
|
|
|
|
### Prerequisites
|
|
* [WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10)
|
|
WSL2 is used in conjunction with Docker to predefine a build environment for Asuro.
|
|
* [Docker for Windows](https://docs.docker.com/docker-for-windows/install/)
|
|
Docker is used to ensure a predefined environment with the correct versions of; Freepascal, Binutils, NASM, Make, xorriso & grub-mk-rescue installed is used for compilation. An ISO will be generated at the end of the build process.
|
|
* [Git (Obviously)](https://git-scm.com/)
|
|
I don't think this needs an explaination.
|
|
* [VSCode (Optional, but highly recommended)](https://code.visualstudio.com/)
|
|
Visual Studio code is our IDE of choice, and we have a number of recommended plugins.
|
|
* [PowerShell Plugin by Microsoft](https://marketplace.visualstudio.com/items?itemName=ms-vscode.powershell)
|
|
This plugin gives you the ability to use the 'PowerShell' task type, allowing the automatic launching of virtualbox with the resulting image generated during compilation of Asuro.
|
|
* [VirtualBox](https://www.virtualbox.org/)
|
|
Virtualbox is our Virtualisation environment of choice, don't ask why, it just is.
|
|
|
|
### Installation (correct as of 2021/06/20)
|
|
1. Install WSL2 as described in the article linked above & ensure Virtualization is enabled in the BIOS.
|
|
2. Ensure WSL2 is used by default with the following command:
|
|
```powershell
|
|
wsl --set-default-version 2
|
|
```
|
|
3. Install Docker for Windows.
|
|
4. Install Git for Windows.
|
|
5. Install VSCode & the listed plugins.
|
|
6. Install VirtualBox (v7+).
|
|
7. Clone this repository.
|
|
8. Run the following command in the root of the repo to build the docker image:
|
|
```powershell
|
|
docker compose build builder
|
|
```
|
|
9. Run the following command to compile Asuro:
|
|
```powershell
|
|
docker compose run builder
|
|
```
|
|
10. Create a new virtual machine in Virtualbox and mount the `Asuro.iso` generated in step 9 as a boot image.
|
|
11. Add the virtualbox installation directory to your `%PATH%` environment variable, usually:
|
|
```
|
|
%PROGRAMFILES%\Oracle\VirtualBox
|
|
```
|
|
12. Naviage to your virtualbox machines folder, this is usually the following
|
|
```
|
|
%userprofile%\VirtualBox VMs\<VM Name>
|
|
```
|
|
Open the Virtual Machine Definition file (.vbox) in your text editor of choice and find the following line:
|
|
```xml
|
|
<Machine uuid="{7d395c96-891c-4139-b77d-9b6b144b0b93}" name="Asuro" OSType="Linux" snapshotFolder="Snapshots" lastStateChange="2021-06-20T20:33:07Z">
|
|
```
|
|
Copy the uuid, in our case `7d395c96-891c-4139-b77d-9b6b144b0b93` & create a `localenv.json` file in the project root with the following content:
|
|
```json
|
|
{
|
|
"VirtualBox":{
|
|
"MachineName":"<YOUR_UUID_OR_MACHINE_NAME>"
|
|
}
|
|
}
|
|
```
|
|
This will allow VSCode to automatically launch VirtualBox once Asuro has been compiled.
|
|
|
|
You can also enable the serial adapter "COM1" in mode "Raw File", give it a path, and provide this path in the `localenv.json` as follows:
|
|
```json
|
|
{
|
|
"VirtualBox" : {
|
|
"MachineName": "<YOUR_UUID_OR_MACHINE_NAME>",
|
|
"LogLocation": "Fully\\Qualified\\Path\\To\\Your\\Log\\File"
|
|
}
|
|
}
|
|
```
|
|
This will allow you to see the console output from Asuro in your host terminal.
|
|
13. Open your project folder in VSCode, use CTRL+SHIFT+B to build & F5 to build + run in VBox.
|
|
14. Congratulations! You can now play with Asuro!
|
|
|
|
### Notes & Gotchas
|
|
- The above process has been updated to be compatible with VirtualBox 7+, in which VBoxSDL was removed and vboxmanage should be used in its place. A small wrapper powershell script is used to achieve this.
|
|
- It was noted that Windows builds above `20H2` seem to have issues installing WSL2. We may have to wait for a patch from Microsoft to fix this. Our devs are currently using build `20H2`.
|