valter/dosbox-staging
1
0
Fork 0
Code Releases Activity

Make MD docs comply with markdownlint

Browse source
This commit is contained in:
krcroft 2020-01-05 19:21:03 -08:00 • committed by Patryk Obara
parent 312a763509
commit a852fe3eab
5 changed files with 110 additions and 98 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.mdlrc Normal file
View file

@ -0,0 +1 @@
rules "~MD005", "~MD033", "~MD046"

58
README.md
View file

@ -1,7 +1,8 @@
# dosbox-staging
[![](https://img.shields.io/github/workflow/status/dreamer/dosbox-staging/Linux%20builds?label=Linux%20builds)](https://github.com/dreamer/dosbox-staging/actions?query=workflow%3A%22Linux+builds%22)
[![](https://img.shields.io/github/workflow/status/dreamer/dosbox-staging/Windows%20builds?label=Windows%20builds)](https://github.com/dreamer/dosbox-staging/actions?query=workflow%3A%22Windows+builds%22)
[![](https://img.shields.io/github/workflow/status/dreamer/dosbox-staging/macOS%20builds?label=macOS%20builds)](https://github.com/dreamer/dosbox-staging/actions?query=workflow%3A%22macOS+builds%22)
[![Linux build status](https://img.shields.io/github/workflow/status/dreamer/dosbox-staging/Linux%20builds?label=Linux%20builds)](https://github.com/dreamer/dosbox-staging/actions?query=workflow%3A%22Linux+builds%22)
[![Windows build status](https://img.shields.io/github/workflow/status/dreamer/dosbox-staging/Windows%20builds?label=Windows%20builds)](https://github.com/dreamer/dosbox-staging/actions?query=workflow%3A%22Windows+builds%22)
[![macOS build status](https://img.shields.io/github/workflow/status/dreamer/dosbox-staging/macOS%20builds?label=macOS%20builds)](https://github.com/dreamer/dosbox-staging/actions?query=workflow%3A%22macOS+builds%22)
This repository attempts to modernize the [DOSBox](https://www.dosbox.com/)
project by using current development practices and tools, fixing issues, adding
@ -9,8 +10,7 @@ features that better support today's systems, and sending patches upstream.
Read more at
[Vogons thread](https://www.vogons.org/viewtopic.php?p=790065#p790065).
## Summary of differences compared to upstream:
## Summary of differences compared to upstream
| | dosbox-staging | DOSBox
|- |- |-
@ -45,43 +45,41 @@ Codecs supported for CD-DA emulation:
| **WAV** | Yes (built-in) | Yes - SDL\_sound 1.2 (internal)<sup>[6],＊</sup>
| **AIFF** | No | Yes - SDL\_sound 1.2 (internal)<sup>[6],＊</sup>
<sup>＊ - SDL 1.2 is not actively maintained any more.</sup>
<sup>† - 22.05 kHz, 44.1 kHz, 48 kHz; mono, stereo</sup>
<sup>‡ - 44.1 kHz stereo only</sup>
<sup>§ - SDL\_sound supports it, but the feature might be broken or DOSBox does not indicate support.</sup>
<sup>＊- SDL 1.2 was last updated 2013-08-17 and SDL\_sound 2008-04-20</sup>\
<sup>† - 22.05 kHz, 44.1 kHz, 48 kHz; mono, stereo</sup>\
<sup>‡ - 44.1 kHz stereo only</sup>\
<sup>§ - Broken or unsupported in either SDL\_sound or DOSBox</sup>
[5]:https://www.dosbox.com/wiki/MOUNT#Mounting_a_CUE.2FBIN-Pair_as_volume
[6]:https://sourceforge.net/p/dosbox/code-0/HEAD/tree/dosbox/trunk/src/dos/cdrom_image.cpp#l536
## Development snapshot builds
Pre-release builds can be downloaded from CI build artifacts. Go to
Pre-release builds can be downloaded from CI build artifacts. Go to
[Linux](https://github.com/dreamer/dosbox-staging/actions?query=workflow%3A%22Linux+builds%22+is%3Asuccess)
or
[Windows](https://github.com/dreamer/dosbox-staging/actions?query=workflow%3A%22Windows+builds%22+is%3Asuccess),
select a build you are interested in, click "**Artifacts**" button (in the top
right), and download the package.
## [Linux](https://github.com/dreamer/dosbox-staging/actions?query=workflow%3A%22Linux+builds%22+is%3Asuccess)
### [Linux](https://github.com/dreamer/dosbox-staging/actions?query=workflow%3A%22Linux+builds%22+is%3Asuccess)
Snapshots are dynamically-linked x86\_64 builds, you'll need additional
packages installed via your package manager.
#### Fedora
$ sudo dnf install libpng SDL2 SDL2_net opusfile
sudo dnf install libpng SDL2 SDL2_net opusfile
#### Debian, Ubuntu
$ sudo apt install libpng16-16 libsdl2-2.0 libsdl2-net-2.0 libopusfile0
sudo apt install libpng16-16 libsdl2-2.0 libsdl2-net-2.0 libopusfile0
#### Arch, Manjaro
$ sudo pacman -S libpng sdl2 sdl2_net opusfile
sudo pacman -S libpng sdl2 sdl2_net opusfile
## [Windows](https://github.com/dreamer/dosbox-staging/actions?query=workflow%3A%22Windows+builds%22+is%3Asuccess)
### [Windows](https://github.com/dreamer/dosbox-staging/actions?query=workflow%3A%22Windows+builds%22+is%3Asuccess)
A dosbox.exe file in a snapshot package is not signed, therefore Windows 10
might prevent the program from starting.
@ -94,11 +92,10 @@ unrecognised app from starting", you have two options to dismiss it:
Windows packages are built for "x86" architecture (in practice it means i686).
## macOS
### macOS
macOS snapshots are not available at the moment.
## Build instructions
### Linux, macOS, MSYS2, MinGW, other OSes
@ -107,11 +104,13 @@ Read [INSTALL](INSTALL) file for a general summary about dependencies and
configure options. Read [build.md](scripts/build.md) for the comprehensive
compilation guide.
$ git clone https://github.com/dreamer/dosbox-staging.git
$ cd dosbox-staging
$ ./autogen.sh
$ ./configure
$ make
``` shell
git clone https://github.com/dreamer/dosbox-staging.git
cd dosbox-staging
./autogen.sh
./configure
make
```
You can also use a helper script [`./scripts/build.sh`](scripts/build.sh),
that performs builds for many useful scenarios (LTO, FDO, sanitizer builds,
@ -123,15 +122,16 @@ First, you need to setup [vcpkg](https://github.com/microsoft/vcpkg) to
install build dependencies. Once vcpkg is installed and bootstrapped, open
PowerShell, and run:
PS> .\vcpkg integrate install
PS> .\vcpkg install libpng sdl2 sdl2-net opusfile
``` powershell
PS:\> .\vcpkg integrate install
PS:\> .\vcpkg install libpng sdl2 sdl2-net opusfile
```
These two steps will ensure that MSVC finds and links all dependencies.
Start Visual Studio, open file: `vs\dosbox.sln` and build all projects
(Ctrl+Shift+B).
## Interop with SVN
This repository is (deliberately) NOT git-svn compatible, this is a pure
@ -156,4 +156,6 @@ Additionally, we attach some optional metadata to the commits imported from SVN
in the form of [Git notes](https://git-scm.com/docs/git-notes). To fetch them,
run:
$ git fetch origin "refs/notes/*:refs/notes/*"
``` shell
git fetch origin "refs/notes/*:refs/notes/*"
```

8
contrib/README.md
View file

@ -1,13 +1,11 @@
Supporting and Contributed Material
===
# Supporting and Contributed Material
This directory holds material that may benefit the users, developers, or
project but that aren't directly part of the core source of the project
itself.
Inventory
====
## Inventory
- **static-opus**: Compiles a static Opusfile library that can be used
by `./configure` in the absense of `pkg-config`
by `./configure` in the absense of `pkg-config`

138
scripts/build.md
View file

@ -13,7 +13,7 @@ Use of both scripts is described below.
## Requirements
- **Windows newer than XP**
- **NTFS-based C:**, because msys2 doesn't work on FAT filesystems
- **NTFS-based C:**, because msys2 doesn't work on FAT filesystems
- **MacOS** 10.x
- **Ubuntu** 16.04 or newer
- **Fedora** up-to-date
@ -23,123 +23,137 @@ Use of both scripts is described below.
## Windows Installation and Usage
1. Download and install Chocolatey: https://chocolatey.org/install
1. Open a console and run Cholocatey's command line interface (CLI) to install msys2 and git:
1. Download and install Chocolatey: <https://chocolatey.org/install>
1. Open a console and run Cholocatey's command line interface (CLI)
to install msys2 and git:
`choco install msys2 git --no-progress`
```
Chocolatey v0.10.15
Installing the following packages:
msys2 git
By installing you accept licenses for the packages.
``` text
Chocolatey v0.10.15
Installing the following packages:
msys2 git
By installing you accept licenses for the packages.
msys2 v20180531.0.0 [Approved]
msys2 package files install completed. Performing other installation steps.
Installing to: C:\tools\msys64
Extracting 64-bit C:\ProgramData\chocolatey\lib\msys2\tools\msys2-base-x86_64-20180531.tar.xz to C:\tools\msys64...
C:\tools\msys64
Extracting 64-bit C:\ProgramData\chocolatey\lib\msys2\tools\msys2-base-x86_64.tar.xz
Extracting C:\tools\msys64\msys2-base-x86_64-20180531.tar to C:\tools\msys64...
C:\tools\msys64
Starting initialization via msys2_shell.cmd
PATH environment variable does not have C:\tools\msys64 in it. Adding...
```
1. Launch a new MSYS2 terminal (not a CMD prompt or Powershell window):
1. Start Menu > Run ... `c:\tools\msys64\msys2_shell.cmd`
1. Run all subsequent steps within this terminal.
1. Start Menu > Run ... `c:\tools\msys64\msys2_shell.cmd`
1. Run all subsequent steps within this terminal.
1. Clone and enter the repository's directory:
1. `git clone https://github.com/dreamer/dosbox-staging.git`
1. `cd dosbox-staging`
1. Run all subsequent steps while residing in the repo's directory.
1. `git clone https://github.com/dreamer/dosbox-staging.git`
1. `cd dosbox-staging`
1. Run all subsequent steps while residing in the repo's directory.
1. (🏁 first-time-only) Install the build tools and package dependencies:
1. (🏁 first-time-only) Install the build tools and package dependencies:
`./scripts/list-build-dependencies.sh -p msys2 | xargs pacman -S --noconfirm`
1. Launch the build script with default settings:
1. Launch the build script with default settings:
`./scripts/build/run.sh --bin-path /mingw64/bin`
## MacOS Installation and Usage
Builds on Mac can be performed with Clang or GCC.
If you only plan on only building with Clang, then follow the Brew installation steps.
If you're interested in building with GCC, then either Brew or MacPorts will work.
Both can be installed without conflicting with eachother.
If you only plan on only building with Clang, then follow the Brew
installation steps. If you're interested in building with GCC, then either
Brew or MacPorts will work. Both can be installed without conflicting with
eachother.
Before installing either, the Xcode tools need to be installed and the license agreed to:
Before installing either, the Xcode tools need to be installed and the license
agreed to:
### Xcode Installation
### Xcode Installation
1. Install the command line tools: `xcode-select --install`
1. Accept the license agreement: `sudo xcodebuild -license`
### Brew Installation
1. Download and install brew per the instructions here: https://brew.sh
1. Download and install brew per the instructions here: <https://brew.sh>
1. Update it with: `brew update`
1. Install git with: `brew install git`
1. Install DOSBox dependencies: `brew install $(./scripts/list-build-dependencies.sh -p brew)`
1. Install DOSBox dependencies:
`brew install $(./scripts/list-build-dependencies.sh -p brew)`
### MacPorts Installation
1. Build and install MacPorts along with DOSBox dependencies with the following sequence:
``` shell
git clone --quiet --depth=1 https://github.com/macports/macports-base.git
cd macports-base
./configure
make -j"$(sysctl -n hw.physicalcpu || echo 4)"
sudo make install
PREFIX="/opt/local"
PATH="${PREFIX}/sbin:${PREFIX}/bin:${PATH}"
sudo port -q selfupdate
sudo port -q install $(/scripts/list-build-dependencies.sh -p macports)
```
``` shell
git clone --quiet --depth=1 https://github.com/macports/macports-base.git
cd macports-base
./configure
make -j"$(sysctl -n hw.physicalcpu || echo 4)"
sudo make install
PREFIX="/opt/local"
PATH="${PREFIX}/sbin:${PREFIX}/bin:${PATH}"
sudo port -q selfupdate
sudo port -q install $(/scripts/list-build-dependencies.sh -p macports)
```
### Build DOSBox (common for all of the above)
1. Clone the repository: `git clone https://github.com/dreamer/dosbox-staging.git`
1. Change directories into the repo: `cd dosbox-staging`
1. Build DOSBox:
- Clang: `./scripts/build.sh --compiler clang --bin-path /usr/local/bin`
- GCC (brew): `./scripts/build.sh --compiler-version 9 --bin-path /usr/local/bin`
- GCC (macports): `./scripts/build.sh --compiler-version mp-9 --bin-path /opt/local/bin`
- Clang: `./scripts/build.sh --compiler clang --bin-path /usr/local/bin`
- GCC (brew): `./scripts/build.sh --compiler-version 9 --bin-path /usr/local/bin`
- GCC (macports): `./scripts/build.sh --compiler-version mp-9 --bin-path /opt/local/bin`
## Linux Installation
1. (🏁 first-time-only) Install dependencies based on your package manager; apt in this example:
`sudo apt install -y $(./scripts/list-build-dependencies.sh -p apt)`
For other supported package managers, run:
`./scripts/list-build-dependencies.sh --help`
1. (🏁 first-time-only) Install dependencies based on your package manager; apt
in this example:
`sudo apt install -y $(./scripts/list-build-dependencies.sh -p apt)`
For other supported package managers, run:
`./scripts/list-build-dependencies.sh --help`
1. Install git: `sudo apt install -y git`
1. Clone the repository: `git clone https://github.com/dreamer/dosbox-staging.git`
1. Change directories into the repo: `cd dosbox-staging`
1. Build DOSBox: `./scripts/build.sh`
## Additional Tips
The compiler, version, and bit-depth can be selected by passing the following common
options to the **list-build-dependencies.sh** and **build.sh** scripts:
* `--compiler clang`, to use CLang instead of GCC
* `--compiler-version 8`, to use a specific version of compiler (if available in your package manager)
* `--bit-depth 32`, to build a 32-bit binary instead of 64-bit
- `--compiler clang`, to use CLang instead of GCC
- `--compiler-version 8`, to use a specific version of compiler
(if available in your package manager)
- `--bit-depth 32`, to build a 32-bit binary instead of 64-bit
After building, your `dosbox` or `dosbox.exe` binary will reside inside `./dosbox-staging/src/`.
Build flags you might be interested in:
* `--lto`, perform optimizations across the entire object space instead of per-file (Only available on Mac and Linux)
* `--release debug`, to build a binary containing debug symbols
* You can run the resulting binary in the GNU debugger: `gdb /path/to/dosbox`, followed by `start mygame.bat`
* `--release profile`, to generate performance statistics
* Instructions are provided after the build completes, which describe how to generate and process the profiling data
* `--release <sanitizer-type>`, to build a binary that performs dynamic code-analysis at runtime (Linux and macOS)
* see `./scripts/build.sh --help` for a list of sanitizer-types that are available
* Run your binary like normal and it will generate output describing problematic behavior
* Some sanitizers accept runtime options via an environment variables, such as `ASAN_OPTIONS`, described here: https://github.com/google/sanitizers/wiki/AddressSanitizerFlags
If you want to run multiple back-to-back builds from the same directory with different settings then
add the `--clean` flag to ensure previous objects and binaries are removed.
- `--lto`, perform optimizations across the entire object space instead of
per-file (Only available on Mac and Linux)
- `--release debug`, to build a binary containing debug symbols
- You can run the resulting binary in the GNU debugger: `gdb /path/to/
dosbox`, followed by `start mygame.bat`
- `--release profile`, to generate performance statistics
- Instructions are provided after the build completes, which describe how to
generate and process the profiling data
- `--release <sanitizer-type>`, to build a binary that performs dynamic
code-analysis at runtime (Linux and macOS)
- see `./scripts/build.sh --help` for a list of sanitizer-types that are
available
- Run your binary like normal and it will generate output describing
problematic behavior
- Some sanitizers accept runtime options via an environment variables,
such as `ASAN_OPTIONS`, described here:
<https://github.com/google/sanitizers/wiki/AddressSanitizerFlags>
If you want to run multiple back-to-back builds from the same directory with
different settings then add the `--clean` flag to ensure previous objects and
binaries are removed.

3
scripts/verify-markdown.sh
View file

@ -3,9 +3,6 @@
# Copyright (C) 2020 Kevin Croft <krcroft@gmail.com>
# SPDX-License-Identifier: GPL-2.0-or-later
#
# Based on `verify-bash.sh` by Patryk Obara <patryk.obara@gmail.com>
# Copyright (C) 2019 licensed GPL-2.0-or-later
#
# This script exists only to easily run mdl (markdownlint) on all
# *.md files in the repo.
#