From a852fe3eab76d8964c47c23bbaf9e525d6730447 Mon Sep 17 00:00:00 2001 From: krcroft Date: Sun, 5 Jan 2020 19:21:03 -0800 Subject: [PATCH] Make MD docs comply with markdownlint --- .mdlrc | 1 + README.md | 58 ++++++++-------- contrib/README.md | 8 +-- scripts/build.md | 138 ++++++++++++++++++++----------------- scripts/verify-markdown.sh | 3 - 5 files changed, 110 insertions(+), 98 deletions(-) create mode 100644 .mdlrc diff --git a/.mdlrc b/.mdlrc new file mode 100644 index 00000000..b250ff0c --- /dev/null +++ b/.mdlrc @@ -0,0 +1 @@ +rules "~MD005", "~MD033", "~MD046" diff --git a/README.md b/README.md index 5c890d1e..f721ab2b 100644 --- a/README.md +++ b/README.md @@ -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)[6],＊ | **AIFF** | No | Yes - SDL\_sound 1.2 (internal)[6],＊ -＊ - SDL 1.2 is not actively maintained any more. -† - 22.05 kHz, 44.1 kHz, 48 kHz; mono, stereo -‡ - 44.1 kHz stereo only -§ - SDL\_sound supports it, but the feature might be broken or DOSBox does not indicate support. +＊- SDL 1.2 was last updated 2013-08-17 and SDL\_sound 2008-04-20\ +† - 22.05 kHz, 44.1 kHz, 48 kHz; mono, stereo\ +‡ - 44.1 kHz stereo only\ +§ - Broken or unsupported in either SDL\_sound or DOSBox [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/*" +``` diff --git a/contrib/README.md b/contrib/README.md index 31805494..0f2385c3 100644 --- a/contrib/README.md +++ b/contrib/README.md @@ -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` diff --git a/scripts/build.md b/scripts/build.md index 0db2bead..1743b66f 100644 --- a/scripts/build.md +++ b/scripts/build.md @@ -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: +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: 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 `, 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 `, 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: + + +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. diff --git a/scripts/verify-markdown.sh b/scripts/verify-markdown.sh index f33c8810..0f024e8c 100755 --- a/scripts/verify-markdown.sh +++ b/scripts/verify-markdown.sh @@ -3,9 +3,6 @@ # Copyright (C) 2020 Kevin Croft # SPDX-License-Identifier: GPL-2.0-or-later # -# Based on `verify-bash.sh` by Patryk Obara -# 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. #