https://github.com/badlogic/dos-dev-template Skip to content Toggle navigation Sign up * Product + Actions Automate any workflow + Packages Host and manage packages + Security Find and fix vulnerabilities + Codespaces Instant dev environments + Copilot Write better code with AI + Code review Manage code changes + Issues Plan and track work + Discussions Collaborate outside of code + Explore + All features + Documentation + GitHub Skills + Blog * Solutions + For + Enterprise + Teams + Startups + Education + By Solution + CI/CD & Automation + DevOps + DevSecOps + Case Studies + Customer Stories + Resources * Open Source + GitHub Sponsors Fund open source developers + The ReadME Project GitHub community articles + Repositories + Topics + Trending + Collections * Pricing [ ] * # In this repository All GitHub | Jump to | * No suggested jump to results * # In this repository All GitHub | Jump to | * # In this user All GitHub | Jump to | * # In this repository All GitHub | Jump to | Sign in Sign up {{ message }} badlogic / dos-dev-template Public * Notifications * Fork 0 * Star 134 Template project for developing DOS games/apps with DJGPP, including source-level remote debugging with GDB and DOSBox. License BSD-2-Clause license 134 stars 0 forks Star Notifications * Code * Issues 1 * Pull requests 0 * Actions * Projects 0 * Security * Insights More * Code * Issues * Pull requests * Actions * Projects * Security * Insights badlogic/dos-dev-template This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository. main Switch branches/tags [ ] Branches Tags Could not load branches Nothing to show {{ refName }} default View all branches Could not load tags Nothing to show {{ refName }} default View all tags Name already in use A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch? Cancel Create 1 branch 0 tags Code * Local * Codespaces * Clone HTTPS GitHub CLI [https://github.com/b] Use Git or checkout with SVN using the web URL. [gh repo clone badlog] Work fast with our official CLI. Learn more. * Open with GitHub Desktop * Download ZIP Sign In Required Please sign in to use Codespaces. Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Launching Xcode If nothing happens, download Xcode and try again. Launching Visual Studio Code Your codespace will open once ready. There was a problem preparing your codespace, please try again. Latest commit @badlogic badlogic Fix release build includes. ... 76a5c9a Dec 23, 2022 Fix release build includes. 76a5c9a Git stats * 29 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time .vscode Use iret to return from signal handlers instead of longjmp Dec 21, 2022 assets Assets and finished README.md Dec 22, 2022 doc Update clangd info. Dec 23, 2022 src Fix release build includes. Dec 23, 2022 tools Source glob (gasp) and README.md beginnings. Dec 22, 2022 .clang-format Formatting. Dec 21, 2022 .gitignore Clean-up gdbstub Dec 21, 2022 CMakeLists.txt Require and use Ninja as the build generator by default. Dec 23, 2022 LICENSE Initial commit Dec 20, 2022 README.md Update README.md Dec 23, 2022 download-tools.sh Actually use Bash as the script interpreter. Dec 23, 2022 View code [ ] DOS demo/game development template Quickstart Guide Installation Project structure Running and debugging Writting code Asset files Building and running from the command line Building Running Debugging FAQ What does download-tools.sh do? How does the debugging work? What are all those files in .vscode? README.md DOS demo/game development template doc/screenshot.png Want to relive the 90ies and create little demos and games for DOS using C/C++ with "modern" tools? Then this project template is for you. It's a turn key solution to setup a develpoment environment to create DOS demos/apps. consisting of: * DJGPP, the GCC-based C/C++ compiler for DOS (DPMI/protected mode). * GDB, the debugger used to debug the DOS demo/game. * DOSBox-x, the bells and whistles DOS-emulator to develop and run the DOS demo/game in. * CMake, to define what needs to be build how. * Visual Studio Code, to tie all the above together and provide an integrated development environment. Quickstart Guide Installation Install: * Git: On Windows, install Git for Windows. You will need Git Bash to run a shell script later. * CMake: ensure cmake is in your PATH. * Ninja + Windows: Put the ninja.exe file somewhere and make sure it's available on the command line via your system PATH. + Linux, e.g. Debian/Ubuntu: sudo apt install ninja-build + macOS, through brew: brew install ninja * Visual Studio Code: ensure command line interface is installed and in your PATH. Open a shell (Git Bash on Windows), then: git clone https://github.com/badlogic/dos-dev-template cd dos-dev-template ./download-tools.sh The download-tools.sh script will download everything you need to start developing for DOS. Once complete, open the dos-dev-template/ folder in Visual Studio Code. The first time you start Visual Studio Code, you may be promoted to install the clangd language service. Make sure you click "Install!" doc/clangd.png You may also be prompted to select a kit. Select djgpp. Project structure .vscode/ <- configuration files for VS Code & extensions assets/ <- files used by the program src/ <- source code goes here main.c <- a little mode 13h demo app tools/ <- contains GDB, DJGPP, DOSBOX after download dosbox-x.conf <- DOSBox-x config enabling debugging via serial port toolchain-djgpp.cmake <- CMake toolchain definition file for DJGPP CMakeLists.txt <- CMake build definition. download-tools.sh <- Script to download GDB, DJGPP, DOSBOX, and Visual Studio Code extensions Running and debugging Open the Run and debug view as shown in the screenshot above, then start one of the two launch configurations: * debug target: builds and launches the currently selected CMake launch target in DOSBox-x, and attaches the debugger. * run target: builds and launches the currently selected CMake launch target in DOSBox-x without attaching a debugger. Make sure the Cmake Build Variant matches the launch configuration, e.g. set the Debug variant when launching debug target, and the Release variant when launching the run target. Otherwise, the debugger may not be able to attach (Release variant when launching debug target), or the program may hang, waiting for the debugger (Debug variant when launching release target) The debugger has a few limitations & gotchas: * You can not set breakpoints while the program is running. Set breakpoints before launching a debugging session, or while the program is halted after hitting a breakpoint, stepped, or was interrupted. * The debugger is quite a bit slower than what you may be used to. This is due to the use of the serial port emulation for communication. * Always make sure to close the DOSBox-x window before launching a new debugging session. * If the debugger appears to be stuck, either wait for it to timeout, or execute the Debug: Stop command from the command palette. * When you click the debugger's Pause button or press F6 to pause the program, you will end up in an interrupt handler. Don't get confused, simply switch to a source file, set a breakpoint and resume. * In general, the debugging support is one big hack, there may be dragons. Still better than printf-ing your way through life! Writting code Easy, just open or create a new .h, .c, or .cpp file in the src/ folder and type away. You will get full code completion, navigation and what young people call "lints". Newly created files will be added to the build automatically. Your code is compiled with DJGPP, which means it will become a beautiful 32-bit protected mode application. Check out the resources below to get your DOS programming juices flowing: * 256-Color VGA Programming in C, a 5 part tutorial on VGA programming, using DJGPP. * The Art of Demomaking, a 16 part series explaining and demonstrating various demo effects, using DJGPP. * Brennan's Guide to Inline Assembly, in case you want to speed up your app with some artisan, hand-crafted assembly. Asset files While you can do a lot with just code, sometimes you need a good old file. Put the files for your program in the assets/ folder. The file will then be available to your program via the path assets/ , which you can pass to e.g. fopen(). Building and running from the command line If you don't like graphical user interfaces, you can also do all of the above from the command line. Building cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_TOOLCHAIN_FILE=tools/toolchain-djgpp.cmake -S . -B build This configures your build to produce a debug binary. For a release binary, specify -DCMAKE_BUILD_TYPE=Release. You generally run this command only when your build type changes. Once configured, you can build the program as follows: cmake --build build This puts the executable file and assets in the build/ directory. Running ./tools/dosbox-x/dosbox-x -fastlaunch -exit -conf tools/dosbox-x.conf build/main.exe Launches the executable in DOSBox-x. Make sure to build with -DCMAKE_BUILD_TYPE=Release before launching. Debugging ./tools/dosbox-x/dosbox-x -fastlaunch -exit -conf tools/dosbox-x.conf build/main.exe Launches the executable in DOSBox-x. Make sure to build with -DCMAKE_BUILD_TYPE=Debug before launching. In a second shell: ./tools/gdb/gdb (gdb) file build/main.exe (gdb) target remote localhost:5123 GDB will connect to the program running in DOSBox-x. See the GDB cheat sheet on how to use the command line driver of GDB. FAQ Here are a few questions you may have, if you want to dig deeper into the entire setup to modify it to your liking. What does download-tools.sh do? It will download the following tools for your operating system to the tools/ folder: * My fork of GDB 7.1a, which is specifically build to debug DOS programs compiled with DJGPP remotely, e.g. running in DOSBox-x. * DJGPP binaries provided by Andrew Wu * My fork of DOSBox-x, which fixes a few things required for debugging, such as serial port emulation through TCP/IP on macOS. After downloading the tools, it will install these Visual Studio Code extensions necessary for C/C++ development: * clangd, the superior C/C++ code completion, navigation, and insights language service. * CMake Tools, for CMake support in VS Code * C/C++ for Visual Studio Code, needed to do anything C/C++ in VS Code. Its less than great intellisense service is replaced by clangd though. * Native Debug Extension, provides the high-level debugger capanble of using GDB. How does the debugging work? I'm glad you ask! It's an unholy ball of duct tape consisting of: * A GDB stub, implemented as a header-file only library. It implements the GDB remote protocol and is included in the program itself, which it will then control and "expose" to the debugger for inspection and modification. It's a heavily modified and extended version of Glenn Engel & Jonathan Brogdon GDB stub, so it can actually do all the things expected of a somewhat modern debugger. I would suggest not looking into that file. It was not build with love or care, just enough spite so it gave up and started working. Mostly. * A custom, minimal build of GDB 7.1a, one of the last versions of GDB to support COFF_GO32 executables as produced by DJGPP. * A modified version of DOSBox-x, which was necessary as serial port communication over TCP/IP was broken on macOS. My pull request was merged, so hopefully this template can switch over to the official DOSBox-x build eventually. And here's how it works: 1. DOSBox-x is configured to expose serial port 0 (COM1) to the outside world via TCP on port 5123 in nullmodem, non-handshake mode. 2. The program is started in DOSBox-x and first calls gdb_start(). This function initializes the serial port to use the highest baud rate possible, then triggers a breakpoint via int 3. This in turn triggers a special signal handler implemented in the GDB stub which listens for incoming data from the serial port. 3. The debugger (GDB) is told to connect to a remote process via TCP at address localhost:5123. This establishes a connection to the signal handler that waits for data coming in on the serial port. 4. GDB sends commands, like set a breakpoint, step, or continue, which the signal handler interprets and executes. 5. As a special case, if the program is running and the debugger wants to interrupt it to set further breakpoints or get information, the GDB stub also hooks the timer interrupt to poll the serial port state. In case there's data waiting, it will call the signal handler, which then takes over processing the new debugger commands. In theory, all of this is very simple. In practice, it can fall apart in the most creative ways. The implementation was tested with the included GDB version, as well as the Native Debugger extension which sits on top the included GDB version. I can make no guarantees it will work with other GDB versions or higher level debuggers as found in e.g. CLion, etc. It should. But it might not, as most debuggers don't stick to the protocol spec. What are all those files in .vscode? These are configuration files for the various extensions and VS Code itself to provide you with a passable out-of-the-box experience. * cmake-kits.json tells the CMake Tools extension about the DJGPP toolchain, which is defined as a CMake toolchain file in tools/ toolchain-djgpp.cmake * launch.json defines the 2 launch configurations debug target and run target. They in turn depend on tasks defined in tasks.json * settings.json turns off the not great C/C++ extension intellisense and configures a few other minor things. About Template project for developing DOS games/apps with DJGPP, including source-level remote debugging with GDB and DOSBox. Resources Readme License BSD-2-Clause license Stars 134 stars Watchers 4 watching Forks 0 forks Releases No releases published Packages 0 No packages published Languages * C 88.2% * Shell 6.9% * CMake 4.9% Footer (c) 2022 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.