Codespaces: Difference between revisions
m (add zip .cdi command) |
m (→Example 1: Build an .elf from a KallistiOS example: forcing the image to display at the right place) |
||
(10 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
Github [https://www.youtube.com/watch?v=sYJ3CHtT6WM Codespaces] lets you spawn a Dreamcast development environment in your browser in a matter of minutes. | Github [https://www.youtube.com/watch?v=sYJ3CHtT6WM Codespaces] lets you spawn a complete Dreamcast development environment in your browser in a matter of minutes. | ||
The only things you need are: | The only things you need are: | ||
* a browser | * a browser | ||
* a github login. | * a github login. | ||
No need for a complex installation process anymore ! | |||
== Steps Overview == | == Steps Overview == | ||
Line 61: | Line 64: | ||
* Go back to the root directory of your repository | * Go back to the root directory of your repository | ||
* Launch your Codespace by clicking on the "<> Code" button, then "Codespaces" - "Create codespace on master". | * Launch your Codespace by clicking on the "<> Code" button, then "Codespaces" - "Create codespace on master". | ||
{| | |||
|[[File:Screen Shot 2024-07-14 at 8.28.13 AM.png|thumb]] | |||
|} | |||
* 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. | * 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 | * 3-bars-Menu at the top left - Terminal - New Terminal | ||
Line 72: | Line 78: | ||
== Example 2: create a .cdi from the .elf of Example 1 == | == 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: | Having an .elf executable file is nice for small tests, but often you'll find yourself needing to build a .cdi disc image file: | ||
* | * If you closed your codespace, you can reopen it by going to your code repository, click on the "<> Code" button, then "Codespaces", then on the auto-generated name of your codespace. | ||
* Since our codespace does not contain mkdcdisc (the tool to build .cdi files), we'll add that to our codespace: | * 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) | ** Open a terminal in your codespace (3-bars-Menu at the top left - Terminal - New Terminal) | ||
Line 81: | Line 87: | ||
** meson compile -C builddir | ** meson compile -C builddir | ||
** cp ./builddir/mkdcdisc /opt/toolchains/dc/bin | ** 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" | ** 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 | ** 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 == | == Example 3: Configuring a more complex Codespace == | ||
If you find yourself always adding extra application into the | 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: | ||
* | * Modify .devcontainer/devcontainer.json so that it points to a Dockerfile: | ||
<syntaxhighlight lang="json"> | <syntaxhighlight lang="json"> | ||
// 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. | ||
<syntaxhighlight lang=" | // "remoteUser": "root" | ||
<syntaxhighlight> | } | ||
</syntaxhighlight> | |||
* ... and add a new file: ./devcontainer/Dockerfile | |||
<syntaxhighlight lang="bash"> | |||
# Stage 1 | |||
FROM "ghcr.io/kos-builds/kos-ports-dc:sha-656a397-14.1.0" as build | |||
# Add mkdcdisc | |||
RUN git clone https://gitlab.com/simulant/mkdcdisc /opt/toolchains/dc/mkdcdisc \ | |||
&& cd /opt/toolchains/dc/mkdcdisc \ | |||
&& meson setup builddir \ | |||
&& meson compile -C builddir \ | |||
&& cp ./builddir/mkdcdisc /opt/toolchains/dc/bin | |||
</syntaxhighlight> | |||
* The next time you create a repository & copy the above 2 files in it, you will get a codespace with mkdcdisc already correctly installed ! | |||
== Example 4: Build something not from KallistiOS == | |||
All the previous examples started by forking the KallistiOS repository, but most often you'll just want to work on your own code / another Dreamcast project, so you'll work from a repository other than KallistiOS: | |||
* login into [https://www.github.com github] | |||
* create/go to your own repository, or fork an existing project (eg doom64-dc, ...) | |||
* add at least ./devcontainer/devcontainer.json, and ./devcontainer/Dockerfile if needed | |||
* create/launch your codespace | |||
* follow the build instructions of that project | |||
* Notes: | |||
** Everything for KallistiOS should be available in the terminal, you'll find KallistiOS stuff in the folder /opt/toolchains/dc | |||
** In the file-tree on the left side, you'll see the files of your repository (folder: /workspaces). If you also want to add other folders there, eg /opt/toolchains/dc, execute something like this in the terminal: code -a /opt/toolchains/dc | |||
== Tips == | == Tips == |
Latest revision as of 18:19, 15 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:
- If you closed your codespace, you can reopen it by going to your code repository, click on the "<> Code" button, then "Codespaces", then on the auto-generated name of your codespace.
- 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:
- Modify .devcontainer/devcontainer.json so that it points to a Dockerfile:
// 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"
}
- ... and add a new file: ./devcontainer/Dockerfile
# Stage 1
FROM "ghcr.io/kos-builds/kos-ports-dc:sha-656a397-14.1.0" as build
# Add mkdcdisc
RUN git clone https://gitlab.com/simulant/mkdcdisc /opt/toolchains/dc/mkdcdisc \
&& cd /opt/toolchains/dc/mkdcdisc \
&& meson setup builddir \
&& meson compile -C builddir \
&& cp ./builddir/mkdcdisc /opt/toolchains/dc/bin
- The next time you create a repository & copy the above 2 files in it, you will get a codespace with mkdcdisc already correctly installed !
Example 4: Build something not from KallistiOS
All the previous examples started by forking the KallistiOS repository, but most often you'll just want to work on your own code / another Dreamcast project, so you'll work from a repository other than KallistiOS:
- login into github
- create/go to your own repository, or fork an existing project (eg doom64-dc, ...)
- add at least ./devcontainer/devcontainer.json, and ./devcontainer/Dockerfile if needed
- create/launch your codespace
- follow the build instructions of that project
- Notes:
- Everything for KallistiOS should be available in the terminal, you'll find KallistiOS stuff in the folder /opt/toolchains/dc
- In the file-tree on the left side, you'll see the files of your repository (folder: /workspaces). If you also want to add other folders there, eg /opt/toolchains/dc, execute something like this in the terminal: code -a /opt/toolchains/dc
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.