Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/joncampbell123/dosbox-x/llms.txt

Use this file to discover all available pages before exploring further.

DOSBox-X welcomes contributions of all kinds — you do not need to be a programmer to make a meaningful difference. Whether you are testing DOS games for compatibility, submitting a bug report, translating a language file, or opening a pull request with a fix, every contribution helps move the project toward its goal of complete pre-2000 DOS and Windows 3.x/9x emulation.
Before opening a new issue or pull request, check the issue tracker first to see whether your contribution is already under discussion.

​
Ways to Contribute

Testing

Run DOS games, demoscene software, and applications; verify Windows 3.x/9x guest support; write unit tests.

Bug Fixes & Code

Submit patches, improvements, and refinements against the main branch via pull request.

Documentation & Translation

Improve the wiki, translate language files, and help package DOSBox-X for different distributions.

Community

Answer questions, share knowledge about DOS games and tricks, and suggest ideas in the issue tracker.

​
Detailed Contribution Areas

​
Testing

Testing is one of the most valuable contributions because it directly improves compatibility for everyone.
1

Test DOSBox-X features

Exercise built-in commands, configuration options, menu functions, and new features added in recent releases. Report any regressions or unexpected behavior in the issue tracker.
2

Test DOS games and applications

Run DOS games and productivity software, particularly titles that are known to use unusual hardware tricks, copy protection, or speed-sensitive code paths. Demoscene productions (especially pre-1996) are especially valuable for testing emulation accuracy.
3

Test Windows guest support

Verify that Windows 1.0, 2.x, 3.x, 95, 98, and ME install and run correctly as guest operating systems inside DOSBox-X. Include notes on configuration settings required to get them working.
4

Write unit tests

Unit tests live in the tests/ directory. Adding coverage for untested functions helps catch regressions automatically. See existing tests for the framework in use.
5

Test new DOS software development

DOSBox-X can serve as an accurate platform for developing new DOS software. The DOSLIB and DOSLIB2 projects provide libraries for this purpose.

​
Bug Fixes and Code Improvements

Code contributions are accepted as pull requests against the master branch on GitHub. Coding standards (from CONTRIBUTING.md):
  • Target C++14 compatibility — all new code must compile as C++14.
  • Follow the .editorconfig file for formatting (most editors support it automatically; see editorconfig.org).
  • Favour short, clear methods over long monolithic functions.
  • Maximise code reuse — do not repeat yourself (DRY principle).
  • Simplify code paths and avoid excessive nesting.
  • Document non-obvious logic. Doxygen-style comments are preferred; self-explanatory method names are acceptable.
Be careful with C integer types. Never assume the width of int or long. Use uint16_t, uint32_t, int32_t, size_t, off_t, and uintptr_t for width-sensitive operations. On 64-bit Linux, sizeof(long) is 64 bits, while on Windows (MSVC/MinGW) it remains 32 bits.
If you are unsure what to work on, browse the issue tracker for bugs labelled as good candidates for a first fix or for feature requests that interest you.

​
Documentation and Translation

  • Wiki — The DOSBox-X Wiki is the primary user documentation. Improvements, new guides, and corrections are welcome.
  • Language files — DOSBox-X supports fully translated UIs via language files (set language= in dosbox-x.conf). Translation files live in contrib/translations/. To generate a template, run CONFIG -wl filename inside DOSBox-X. Currently available translations include Chinese (Simplified and Traditional), Dutch, French, German, Hungarian, Italian, Japanese, Korean, Portuguese (Brazilian), Russian, Spanish, and Turkish — speakers of other languages are encouraged to add more.
  • Software packaging — Creating and maintaining packages for Linux distributions (Flatpak, RPM, DEB) and other platforms is a practical contribution that helps users on those platforms.

​
Community Support

  • Answer questions from other users in the issue tracker and community channels (see the Discord link on the project homepage).
  • Share notes on specific DOS games, Windows 9x applications, hardware tricks, copy protection schemes, or other compatibility knowledge.
  • Suggest ideas and improvements — even if a feature cannot be implemented immediately, well-described ideas help prioritise future development.

​
Development and Release Pattern

Understanding the release cycle helps you time contributions for maximum impact.
1

Month opens — new features accepted

On the first day of each month a new release is published. After the release, development reopens for new features, refactors, and pull requests.
2

Feature freeze (~6 days before month end)

Approximately 6 days before the end of the month, only bug fixes are accepted. Feature pull requests opened at this point will be deferred to the next cycle.
3

Build day (last day of month)

The final day of the month is the build day — no source code changes, pull requests, or bug fixes are merged. This day is reserved for producing the release binaries.
Bug-fix pull requests submitted close to the end of the month may still be accepted. Feature pull requests opened in the freeze window will be reviewed and merged at the start of the next month.

​
Pull Request Guidelines

1

Fork the repository

Create a personal fork of joncampbell123/dosbox-x on GitHub.
2

Create a branch and make your changes

Work on a dedicated branch. Keep each pull request focused on a single fix or feature to make review easier.
3

Build and test locally

Confirm your change compiles cleanly and does not break existing behaviour. See the Building DOSBox-X guide for platform-specific build instructions.
4

Open a pull request

Submit your pull request against the master branch. Describe what the change does, why it is needed, and how you tested it.
If your patch is not accepted into the main project, you are welcome to maintain it in your own fork. The DOSBox-X project encourages forks — several active forks already exist for specialised use cases (word processing, Windows 3.x, web browser deployment).

​
Source Code Structure

The table below summarises the key directories to help you navigate the codebase before making changes.
PathContents
src/shell/DOS shell (COMMAND.COM emulation), batch file handling, internal commands (DIR, COPY, SET, etc.)
src/gui/SDL entry point (sdlmain.cpp), input mapper, menus, rendering pipeline, MIDI output
src/output/Display output backends: surface, OpenGL, Direct3D, TrueType font (TTF)
src/dos/DOS kernel emulation, file systems, drive handling
src/cpu/CPU cores (normal, simple, prefetch, dynamic x86, 8086/286), paging, MMX, FPU, flags
src/hardware/Hardware device emulation: VGA/SVGA/PC-98, Sound Blaster, OPL, mixer, PCI, memory, I/O
src/debug/Built-in debugger, breakpoint handling, disassembler, log system
src/builtin/Built-in DOS executables (MEM.COM, EDIT.COM, XCOPY.EXE, etc.) stored as byte arrays
src/misc/Cross-platform utilities, configuration management, message translation
src/aviwriter/AVI writer library supporting OpenDML files beyond the 2 GB limit
include/Header files shared across the codebase
tests/Unit tests
experiments/Experimental features and proofs of concept for future versions
patch-integration/Community patches under consideration for merging
contrib/translations/Language files for UI translation

​
Entry Point and Control Flow

The emulator starts in src/gui/sdlmain.cpp. On Linux and macOS the real main() is used; on Windows, SDL redirects WinMain() to main(). Global configuration state (from dosbox-x.conf and the command line) is accessible through the global control pointer. Most sections and settings are registered in src/dosbox.cpp via DOSBox_SetupConfigSections().

​
Callback System

Much of the DOS and BIOS emulation uses the callback mechanism in src/cpu/callback.cpp. Each BIOS interrupt and DOS kernel entry point (e.g. INT 21h → DOS21_Handler()) is implemented as a native C++ callback triggered by a special invalid opcode (0xFE 0x38 <uint16_t>) injected into the emulated x86 address space.

​
Code of Conduct

All contributors are expected to follow the project’s Code of Conduct. Please read it before participating in issues, pull requests, or community discussions.

Issue Tracker

Report bugs, request features, and browse existing discussions.

DOSBox-X Wiki

User guides, configuration reference, and compatibility notes.

DOSLIB

Library for developing new DOS software — useful for testing DOSBox-X hardware emulation accuracy.

Development Builds

Nightly preview builds for all platforms, useful for testing recent changes before a release.

Build docs developers (and LLMs) love

Get started for freeTalk to us