GitHub - badlogic/dos-dev-template: Template project for developing DOS games/ap...
source link: https://github.com/badlogic/dos-dev-template
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
DOS demo/game development template
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 yourPATH
. - 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
- 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!"
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 launchingdebug target
, and theRelease
variant when launching therun target
. Otherwise, the debugger may not be able to attach (Release
variant when launchingdebug target
), or the program may hang, waiting for the debugger (Debug
variant when launchingrelease 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 pressF6
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/<your-file-name>
, 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.
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:
- DOSBox-x is configured to expose serial port 0 (COM1) to the outside world via TCP on port 5123 in nullmodem, non-handshake mode.
- 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 viaint 3
. This in turn triggers a special signal handler implemented in the GDB stub which listens for incoming data from the serial port. - 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.
- GDB sends commands, like set a breakpoint, step, or continue, which the signal handler interprets and executes.
- 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
andrun 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.
Recommend
-
90
README.md 基...
-
74
2014年微软曾在计算机历史博物馆公开了 MS-DOS1.1和2.0 和 WordforWindows1.1a的源代码。今天,微软已经在GitHub上面开源了MS-DOS1.25和MS-DOS2.0。微软称GitHub上面比原本压缩包形式更加容易被搜索和阅读,也建
-
47
2014 年微软曾在计算机历史博物馆 公开了 MS-DOS 1.1 和 2.0 和 Word for Windows 1.1a 的...
-
68
README.md
-
8
MiniWASM - A minimalist Rust WebAssembly project template This is a minimal Rust-powered WebAssembly application template. It was designed to showcase what must be done to get Rust-powered WebAssembly going with only a small amount o...
-
30
Raspberry Pi Pico template project Dependencies: All Nim dependencies can be fetched(after nimble is installed, I suggest using choosenim for installing Nim.) with, nimb...
-
10
Python Project Template A low dependency and really simple to start project template for Python Projects. See also Flask-Project-Template for a full feature...
-
7
DOS Subsystem for Linux A WSL alternative for users who prefer an MS-DOS environment. DOS Subsystem for Linux integrates a real Linux environment into MS-DOS systems, allowing users to make use of both DOS and Linux applications from...
-
6
README.md ...
-
2
...
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK