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:
* 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 [https://github.com 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 [https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#monthly-included-storage-and-core-hours-for-personal-accounts 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 [https://github.com github]
* Got to [https://github.com/KallistiOS/KallistiOS 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:
<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.
// "remoteUser": "root"
}
</syntaxhighlight>
* 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 [https://dreamcast.wiki/Coder%27s_cable Coder's Cable] or a [https://dreamcast.wiki/Broadband_adapter 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:
<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.
// "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://github.com/KallistiOS/KallistiOS.git /opt/toolchains/dc/kos \
&& cd /opt/toolchains/dc/kos \
&& cp ./doc/environ.sh.sample ./environ.sh \
&& source environ.sh \
&& make
RUN git clone https://gitlab.com/simulant/mkdcdisc /opt/toolchains/dc/mkdcdisc \
&& cd mkdcdisc
&& meson setup builddir
&& meson compile -C builddir
&& cp ./builddir/mkdcdisc /opt/toolchains/dc/bin
</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.

Codespaces

2024-07-14T06:49:08Z

Tchan: completing example 3, added info on reopening codespaces

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:
* 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 [https://github.com 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 [https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#monthly-included-storage-and-core-hours-for-personal-accounts 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 [https://github.com github]
* Got to [https://github.com/KallistiOS/KallistiOS 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:
<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.
// "remoteUser": "root"
}
</syntaxhighlight>
* 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 [https://dreamcast.wiki/Coder%27s_cable Coder's Cable] or a [https://dreamcast.wiki/Broadband_adapter 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:
<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.
// "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://github.com/KallistiOS/KallistiOS.git /opt/toolchains/dc/kos \
&& cd /opt/toolchains/dc/kos \
&& cp ./doc/environ.sh.sample ./environ.sh \
&& source environ.sh \
&& make
RUN git clone https://gitlab.com/simulant/mkdcdisc /opt/toolchains/dc/mkdcdisc \
&& cd mkdcdisc
&& meson setup builddir
&& meson compile -C builddir
&& cp ./builddir/mkdcdisc /opt/toolchains/dc/bin
<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.

Codespaces

2024-07-13T21:32:31Z

Tchan: add placeholder for Example 4

2024-07-13T19:06:10Z

Tchan: finishing Example 1 (Kos example elf)

Codespaces

2024-07-13T18:28:09Z

Tchan: small changes

Codespaces

2024-07-13T17:19:20Z

Tchan: /* Steps Overview */ added free hours info

2023-07-07T20:27:23Z

Tchan: moved Linux disclaimer about custom speeds into the baudrate section

The '''coder's cable''' is the name given to the serial-based cable some developers use to test and debug code during development. Originally, cables were connected to host devices via serial, but modern cable designs incorporate a USB controller instead. Coder's cables can also be used for other purpose's besides development, such as transferring VMU data back to a PC or dumping GD-ROMs (although quite slowly).

== How to build/buy a cable ==
* Buy:
** eg [https://www.retroonyx.com/product-page/dreamcast-usb-coders-cable retroonyx cable], FTDI-based cable.
** (only mentioned for historical purposes - not sold anymore since long - "Lik-Sang coder's cable" - max speed of 781250)
* Build:
** DC serial connector:
*** best connector today is the one used by the [https://www.ebay.com/sch/i.html?_nkw=DC+SD+Adapter+V2 DC SD Adapter V2] (+- 16 USD)
{|
| [[File:DC SD Adapter V2.jpg|thumb|alt=DC SD Adapter V2|DC SD Adapter V2]]
|}
** select a usb-to-serial chip/cable (+- 10 USD)
*** [https://www.silabs.com/interface/usb-bridges/usbxpress Silicon Labs '''CP2102N''']:
**** Supports 1600000, which is a 2,4% baudrate mismatch with the Dreamcast, which seems acceptable for high speeds. Best chip that can be recommended today. Tests give speeds of 170-190 kByte/sec and more thanks to compression.
**** eg [https://www.adafruit.com/product/5335 Adafruit CP2102N Friend (USB-C)]
**** eg [https://www.silabs.com/development-tools/interface/cp2102n-mini-development-kit?tab=overview Silicon Labs CP2102N-MINIEK (mini USB)]
**** eg [https://www.amazon.co.uk/DSD-TECH-SH-U09BL-Serial-CP2102N/dp/B08JLRP6YV DSD TECH SH-U09BL USB to TTL Serial Cable with CP2102N Chip]
*** FDTI's '''FT232R'''-like chips:
**** '''good until 781250''', does not support 1562500.
**** 500000 and 1500000 will not work with all chips/on all pc, because of a 4% baud rate mismatch with the baudrates of the Dreamcast.
***** Even if you're lucky, you won't really get 1500000-worthy speeds - more probably around 130-150 kByte/sec...

** connect the following pins (cfr [[Serial_interface]]):
*** GND <-> GND
*** TXD <-> RXD
*** RXD <-> TXD
*** RTS <-> CTS
*** CTS <-> RTS

== Software to use ==
[[Dcload-serial]]

== Supported Baud Rates ==
'''Not all common baudrates work''', so the recommendations are:
* '''up until 115200''', you can use the common baudrates: 9600, 19200, 38400, 57600, 115200
** if 115200 does not work, you can add the "-e" speedhack option
* '''higher baudrates''':
** try first with the '''dreamcast-specific baudrates''' (223214, 260416, 312500, 390625, '''520833, 781250, 1562500''')
*** Disclaimer for Linux only: Requires a patch to support custom speeds that is not yet part of dc-load-ser 1.0.6.
** '''230400''': use the -e speedhack option if you absolutely need 230400 at pc-side, but the DC will use 223214 or 260416 anyways.
** '''500000 and 1500000''': you can try, but that will not work on all pc (the mismatch with the baudrate of the Dreamcast is sometimes too big (4%))

{{DCWiki:Stub}}

Coder's cable

2023-07-06T17:34:06Z

Tchan: corrected info about lik-sang cable

The '''coder's cable''' is the name given to the serial-based cable some developers use to test and debug code during development. Originally, cables were connected to host devices via serial, but modern cable designs incorporate a USB controller instead. Coder's cables can also be used for other purpose's besides development, such as transferring VMU data back to a PC or dumping GD-ROMs (although quite slowly).

== How to build/buy a cable ==
* Buy:
** eg [https://www.retroonyx.com/product-page/dreamcast-usb-coders-cable retroonyx cable], FTDI-based cable.
** (only mentioned for historical purposes - not sold anymore since long - "Lik-Sang coder's cable" - max speed of 781250)
* Build:
** DC serial connector:
*** best connector today is the one used by the [https://www.ebay.com/sch/i.html?_nkw=DC+SD+Adapter+V2 DC SD Adapter V2] (+- 16 USD)
{|
| [[File:DC SD Adapter V2.jpg|thumb|alt=DC SD Adapter V2|DC SD Adapter V2]]
|}
** select a usb-to-serial chip/cable (+- 10 USD)
*** [https://www.silabs.com/interface/usb-bridges/usbxpress Silicon Labs '''CP2102N''']:
**** Supports 1600000, which is a 2,4% baudrate mismatch with the Dreamcast, which seems acceptable for high speeds. Best chip that can be recommended today. Tests give speeds of 170-190 kByte/sec and more thanks to compression.
**** Disclaimer for Linux only: Requires a patch to support custom speeds that is not yet part of dc-load-ser 1.0.6.
**** eg [https://www.adafruit.com/product/5335 Adafruit CP2102N Friend (USB-C)]
**** eg [https://www.silabs.com/development-tools/interface/cp2102n-mini-development-kit?tab=overview Silicon Labs CP2102N-MINIEK (mini USB)]
**** eg [https://www.amazon.co.uk/DSD-TECH-SH-U09BL-Serial-CP2102N/dp/B08JLRP6YV DSD TECH SH-U09BL USB to TTL Serial Cable with CP2102N Chip]
*** FDTI's '''FT232R'''-like chips:
**** '''good until 781250''', does not support 1562500.
**** 500000 and 1500000 will not work with all chips/on all pc, because of a 4% baud rate mismatch with the baudrates of the Dreamcast.
***** Even if you're lucky, you won't really get 1500000-worthy speeds - more probably around 130-150 kByte/sec...

** connect the following pins (cfr [[Serial_interface]]):
*** GND <-> GND
*** TXD <-> RXD
*** RXD <-> TXD
*** RTS <-> CTS
*** CTS <-> RTS

== Software to use ==
[[Dcload-serial]]

== Supported Baud Rates ==
'''Not all common baudrates work''', so the recommendations are:
* '''up until 115200''', you can use the common baudrates: 9600, 19200, 38400, 57600, 115200
** if 115200 does not work, you can add the "-e" speedhack option
* '''higher baudrates''':
** try first with the '''dreamcast-specific baudrates''' (223214, 260416, 312500, 390625, '''520833, 781250, 1562500''')
** '''230400''': use the -e speedhack option if you absolutely need 230400 at pc-side, but the DC will use 223214 or 260416 anyways.
** '''500000 and 1500000''': you can try, but that will not work on all pc (the mismatch with the baudrate of the Dreamcast is sometimes too big (4%))

{{DCWiki:Stub}}

Coder's cable

2023-07-06T16:31:28Z

Tchan:

The '''coder's cable''' is the name given to the serial-based cable some developers use to test and debug code during development. Originally, cables were connected to host devices via serial, but modern cable designs incorporate a USB controller instead. Coder's cables can also be used for other purpose's besides development, such as transferring VMU data back to a PC or dumping GD-ROMs (although quite slowly).

== How to build/buy a cable ==
* Buy:
** eg [https://www.retroonyx.com/product-page/dreamcast-usb-coders-cable retroonyx cable], FTDI-based cable.
** (only mentioned for historical purposes - not sold anymore since long - "Lik-Sang coder's cable" - max speed of 781250 if combined with CP2102N-chip)
* Build:
** DC serial connector:
*** best connector today is the one used by the [https://www.ebay.com/sch/i.html?_nkw=DC+SD+Adapter+V2 DC SD Adapter V2] (+- 16 USD)
{|
| [[File:DC SD Adapter V2.jpg|thumb|alt=DC SD Adapter V2|DC SD Adapter V2]]
|}
** select a usb-to-serial chip/cable (+- 10 USD)
*** [https://www.silabs.com/interface/usb-bridges/usbxpress Silicon Labs '''CP2102N''']:
**** Supports 1600000, which is a 2,4% baudrate mismatch with the Dreamcast, which seems acceptable for high speeds. Best chip that can be recommended today. Tests give speeds of 170-190 kByte/sec and more thanks to compression.
**** Disclaimer for Linux only: Requires a patch to support custom speeds that is not yet part of dc-load-ser 1.0.6.
**** eg [https://www.adafruit.com/product/5335 Adafruit CP2102N Friend (USB-C)]
**** eg [https://www.silabs.com/development-tools/interface/cp2102n-mini-development-kit?tab=overview Silicon Labs CP2102N-MINIEK (mini USB)]
**** eg [https://www.amazon.co.uk/DSD-TECH-SH-U09BL-Serial-CP2102N/dp/B08JLRP6YV DSD TECH SH-U09BL USB to TTL Serial Cable with CP2102N Chip]
*** FDTI's '''FT232R'''-like chips:
**** '''good until 781250''', does not support 1562500.
**** 500000 and 1500000 will not work with all chips/on all pc, because of a 4% baud rate mismatch with the baudrates of the Dreamcast.
***** Even if you're lucky, you won't really get 1500000-worthy speeds - more probably around 130-150 kByte/sec...

** connect the following pins (cfr [[Serial_interface]]):
*** GND <-> GND
*** TXD <-> RXD
*** RXD <-> TXD
*** RTS <-> CTS
*** CTS <-> RTS

== Software to use ==
[[Dcload-serial]]

== Supported Baud Rates ==
'''Not all common baudrates work''', so the recommendations are:
* '''up until 115200''', you can use the common baudrates: 9600, 19200, 38400, 57600, 115200
** if 115200 does not work, you can add the "-e" speedhack option
* '''higher baudrates''':
** try first with the '''dreamcast-specific baudrates''' (223214, 260416, 312500, 390625, '''520833, 781250, 1562500''')
** '''230400''': use the -e speedhack option if you absolutely need 230400 at pc-side, but the DC will use 223214 or 260416 anyways.
** '''500000 and 1500000''': you can try, but that will not work on all pc (the mismatch with the baudrate of the Dreamcast is sometimes too big (4%))

{{DCWiki:Stub}}