Codespaces: Difference between revisions
m (example 2 refinements) |
m (add placeholder for Example 4) |
||
Line 103: | Line 103: | ||
<syntaxhighlight lang="json"> | <syntaxhighlight lang="json"> | ||
<syntaxhighlight> | <syntaxhighlight> | ||
== Example 4: Build something not from KallistiOS == | |||
* TODO | |||
== Tips == | == Tips == |
Revision as of 21:32, 13 July 2024
Github Codespaces lets you spawn a complete Dreamcast development environment in your browser in a matter of minutes.
The only things you need are:
- a browser
- a github login.
No need for a complex installation process anymore !
Steps Overview
The main steps to get a Codespace working, are:
- Login into github
- Create your code repository, or fork one
- Add a .devcontainer/devcontainer.json file to that repository
- Create & launch your codespace, and enjoy the IDE in your browser !
That's all there is to it.
Free github accounts get 120 free core hours per month.
Example 1: Build an .elf from a KallistiOS example
To compile the executable .elf file from a KallistiOS examples in a Codespace:
- Login into github
- Got to the KallistiOS repository
- Click on the "Fork" button, this will create a KallistiOS repository inside your account
- Click on the "Add File" button, then "Create New File"
- Name the file: ".devcontainer/devcontainer.json", and paste the following contents:
// For format details, see https://aka.ms/devcontainer.json.
// For config options, see the README at: https://github.com/devcontainers/templates/tree/main/src/alpine
{
"name": "My_Codespace",
// Either use a pre-built image (= a Docker container)...
"image": "ghcr.io/kos-builds/kos-ports-dc:sha-656a397-14.1.0",
// ... or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
//"build": { // Path is relative to the devcontainer.json file.
// "dockerfile": "Dockerfile"
//},
// Features to add to the dev container. More info: https://containers.dev/features.
// "features": {},
// Use 'forwardPorts' to make a list of ports inside the container available locally.
// "forwardPorts": [],
// Use 'postCreateCommand' to run commands after the container is created.
//"postCreateCommand": "source /opt/toolchains/dc/kos/environ.sh",
// Configure tool-specific properties.
"customizations": {
"vscode": {
"extensions": [
"ms-vscode.cpptools"
]
}
}
// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
// "remoteUser": "root"
}
- Click on "Commit changes", then "Commit Changes" again to save the file
- Go back to the root directory of your repository
- Launch your Codespace by clicking on the "<> Code" button, then "Codespaces" - "Create codespace on master".
- This will launch Visual Studio Code in your browser. The first time it will take a couple of minutes to launch, after that it will be faster.
- 3-bars-Menu at the top left - Terminal - New Terminal
- cd examples/dreamcast/2ndmix
- make clean
- make
- You should now have a "2ndmix.elf" in that folder
- Navigate to that folder (examples/dreamcast/2ndmix) on the file tree on the left, right-click on the file, and choose "Download..."
- Congratulations ! You successfully built an executable file for the Dreamcast. You can now upload that file in your favorite emulator, or send it to a real Dreamcast via a Coder's Cable or a Broadband Adapter
Example 2: create a .cdi from the .elf of Example 1
Having an .elf executable file is nice for small tests, but often you'll find yourself needing to build a .cdi disc image file:
- TODO: reopen codespace if needed
- Since our codespace does not contain mkdcdisc (the tool to build .cdi files), we'll add that to our codespace:
- Open a terminal in your codespace (3-bars-Menu at the top left - Terminal - New Terminal)
- cd /opt/toolchains/dc
- git clone https://gitlab.com/simulant/mkdcdisc
- cd mkdcdisc
- meson setup builddir
- meson compile -C builddir
- cp ./builddir/mkdcdisc /opt/toolchains/dc/bin
- Build the .cdi file for 2ndmix.elf
- cd /opt/toolchains/dc/kos/examples/dreamcast/2ndmix
- mkdcdisc -e 2ndmix.elf -o 2ndmix.cdi -n "2ndmix"
- Compress the .cdi file into a zip file with parts of max 25 MegaBytes (otherwise your browser will have problems downloading the .cdi):
- zip -s 25M 2ndmix.zip 2ndmix.cdi
- Right-click on the generated files, and download them into your local folders
- Unzip the files in your local folder to reconstruct 2ndmix.cdi
- Launch 2ndmix.cdi in your favorite emulator, or on a real Dreamcast
Example 3: Configuring a more complex Codespace
If you find yourself always adding the same extra application into the codespace provided in Example 1 (eg: always having to add mkdcdisc, ...), you can simplify your setup by specifying your own Dockerfile, and add setup commands in there:
- TODO: devcontainer.json
<syntaxhighlight lang="json"> <syntaxhighlight>
- TODO: Dockerfile
<syntaxhighlight lang="json"> <syntaxhighlight>
Example 4: Build something not from KallistiOS
- TODO
Tips
- When you're finished with your Codespace, go to
- the 3-bars-Menu at the top left - "My Codespaces"
- on the left, select the codespace you were just running
- click on the 3 dots next to "Active"
- select "Stop codespace"
Doing this pro-actively will save you some free minutes, since the default timeout is 30 minutes.