From d6a66b17459c33b41b9d526023b749a7544ea907 Mon Sep 17 00:00:00 2001 From: icex2 Date: Sat, 12 Jun 2021 22:35:55 +0200 Subject: [PATCH] Add development.md documentation Move stuff from root README and add a few more things that I took from BT5. --- README.md | 73 +++------------------------- doc/development.md | 117 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 124 insertions(+), 66 deletions(-) create mode 100644 doc/development.md diff --git a/README.md b/README.md index f7dd0a0..e6dcd78 100644 --- a/README.md +++ b/README.md @@ -20,71 +20,12 @@ Loaders and hardware emulators for SEGA games that run on the Nu and ALLS platfo For setup and configuration guides, refer to the dedicated documents available for each game, see [the links in the previous section](#list-of-supported-games). +## Contributors + +If you are/want to be a contributor of any kind, e.g. new features, bug fixes, documentation improvements, ..., please +read the [contributing documentation](CONTRIBUTING.md), first. + ## Developers -### Building - -The root `Makefile` contains various targets that allow you to build the project easily. - -#### Local build - -For a local build, you need to install Meson and a recent build of MinGW-w64. Then you can start the -build process: - -```shell -make build -``` - -Build output will be located in `build/build32` and `build/build64` folders. - -#### Cleanup local build - -```shell -make clean -``` - -#### Create distribution package (zip file) - -```shell -make dist -``` - -The output will be located in `build/zip`. - -#### Build and create distribution package using docker - -You can also build using docker which avoids having to setup a full development environment if you -are just interested in building binaries of the latest changes. Naturally, this requires you to -have the docker daemon installed. - -```shell -make build-docker -``` - -Once completed successfully, the build output is located in the `build/docker/zip` sub-folder. - -#### Building with Docker Desktop on Windows - -* [Install WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10) -* [Install Docker Desktop](https://docs.docker.com/docker-for-windows/install/) -* Run Docker Desktop to start the Docker Engine -* Open a command prompt (`cmd.exe`) and `cd` to your `segatools` folder -* Run `docker-build.bat` -* Once completed successfully, build output is located in the `build/docker/zip` sub-folder. - -#### Building with Docker on Windows using WSL2 - -* [Install WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10) -* Regarding Linux distribution, we recommend using Ubuntu 20.04 -* Run the "Ubuntu 20.04 LTS" App which opens a Linux shell -* Install `make` and `docker` by running - * `sudo apt-get update` - * `sudo apt-get install make docker.io` -* Add the current user to the docker group that you don't have to run docker commands with root: -`sudo usermod -a -G docker $USER` -* Run the docker daemon in the background: `sudo dockerd > /dev/null 2>&1 &` -* Navigate to your segatools folder. If it is located on the `C:` drive, WSL automatically provides -a mountpoint for that under `/mnt/c`, e.g. `cd /mnt/c/segatools` (if the folder `segatools` is -located under `C:\segatools` on Windows). -* Build segatools: `make build-docker` -* Once completed successfully, build output is located in the `build/docker/zip` sub-folder. +For development setup and instructions how to build the project, refer to the +[dedicated development documentation](doc/development.md). diff --git a/doc/development.md b/doc/development.md new file mode 100644 index 0000000..8f3a4ab --- /dev/null +++ b/doc/development.md @@ -0,0 +1,117 @@ +# Development + +This document is intended for developers interested in contributing to segatools. Please read this document before +you start developing/contributing. + +## Goals + +We want you to understand what this project is about and its goals. The following list serves as a guidance for all +developers to identify valuable contributions for this project. As the project evolves, these gaols might do as well. + +* Allow running Sega arcade (rhythm) games on arbitrary hardware + * Emulate required software and hardware features + * Provide means to cope with incompatibility issues resulting from using a different software platform (e.g. version of Windows). +* Provide an API for custom interfaces and configuring fundamental application features + +## Development environment + +The following tooling is required in order to build this project. + +### Tooling + +#### Linux / MacOSX + +* git +* make +* mingw-w64 +* docker (optional) + +On MacOSX, you can use homebrew or macports to install these packages. + +#### Windows + +TODO + +### IDE + +Ultimately, you are free to use whatever you feel comfortable with for development. The following is our preferred +development environment which we run on a Linux distribution of our choice: + +* Visual Studio Code with the following extensions + * C/C++ + * C++ Intellisense + +### Further tools for testing and debugging + +* Debugger: Can be part of your reverse engineering IDE of your choice or stand-along like +[OllyDbg](http://www.ollydbg.de/) +* [apitrace](https://apitrace.github.io/): Trace render calls to graphics APIs like D3D and OpenGL. +This tool allows you to record and re-play render calls of an application with frame-by-frame +debugging. Very useful to analyze the render pipeline or debug graphicial glitches + +## Building + +The root `Makefile` contains various targets that allow you to build the project easily. + +### Local build + +For a local build, you need to install Meson and a recent build of MinGW-w64. Then you can start the +build process: + +```shell +make build +``` + +Build output will be located in `build/build32` and `build/build64` folders. + +### Cleanup local build + +```shell +make clean +``` + +### Create distribution package (zip file) + +```shell +make dist +``` + +The output will be located in `build/zip`. + +### Build and create distribution package using docker + +You can also build using docker which avoids having to setup a full development environment if you +are just interested in building binaries of the latest changes. Naturally, this requires you to +have the docker daemon installed. + +```shell +make build-docker +``` + +Once completed successfully, the build output is located in the `build/docker/zip` sub-folder. + +### Building with Docker Desktop on Windows + +* [Install WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10) +* [Install Docker Desktop](https://docs.docker.com/docker-for-windows/install/) +* Run Docker Desktop to start the Docker Engine +* Open a command prompt (`cmd.exe`) and `cd` to your `segatools` folder +* Run `docker-build.bat` +* Once completed successfully, build output is located in the `build/docker/zip` sub-folder. + +### Building with Docker on Windows using WSL2 + +* [Install WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10) +* Regarding Linux distribution, we recommend using Ubuntu 20.04 +* Run the "Ubuntu 20.04 LTS" App which opens a Linux shell +* Install `make` and `docker` by running + * `sudo apt-get update` + * `sudo apt-get install make docker.io` +* Add the current user to the docker group that you don't have to run docker commands with root: +`sudo usermod -a -G docker $USER` +* Run the docker daemon in the background: `sudo dockerd > /dev/null 2>&1 &` +* Navigate to your segatools folder. If it is located on the `C:` drive, WSL automatically provides +a mountpoint for that under `/mnt/c`, e.g. `cd /mnt/c/segatools` (if the folder `segatools` is +located under `C:\segatools` on Windows). +* Build segatools: `make build-docker` +* Once completed successfully, build output is located in the `build/docker/zip` sub-folder \ No newline at end of file