Codespaces: Difference between revisions

From dreamcast.wiki
Jump to navigation Jump to search
m (add placeholder for Example 4)
m (→‎Example 1: Build an .elf from a KallistiOS example: forcing the image to display at the right place)
 
(8 intermediate revisions by 2 users not shown)
Line 64: 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 75: 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:
* TODO: reopen codespace if needed
* 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 96: Line 99:
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:
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
* Modify .devcontainer/devcontainer.json so that it points to a Dockerfile:
<syntaxhighlight lang="json">
<syntaxhighlight lang="json">
<syntaxhighlight>
// 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": {},


* TODO: Dockerfile
// Use 'forwardPorts' to make a list of ports inside the container available locally.
<syntaxhighlight lang="json">
// "forwardPorts": [],
<syntaxhighlight>
 
// 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"
}
</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 ==
== Example 4: Build something not from KallistiOS ==
* TODO
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".
Screen Shot 2024-07-14 at 8.28.13 AM.png
  • 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.