Merge pull request #39 from jon-axon/development

Development

.cargo/config.toml

@@ -0,0 +1,2 @@
+[target.x86_64-pc-windows-msvc]
+rustflags = ["-C", "target-feature=+crt-static"]

Cargo.toml

@@ -2,9 +2,13 @@
 name = "chipolata"
 version = "1.0.0"
 edition = "2021"
+license = "MIT"
 build = "build.rs"
-
-# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+repository = "https://github.com/jon-axon/chipolata"
+readme = "README.md"
+description = """
+Chipolata: a CHIP-8/SUPER-CHIP interpreter
+"""
 
 [dependencies]
 eframe = "0.21.2"

README.md

@@ -1,4 +1,4 @@
-# Chipolata: a CHIP-8/SUPER-CHIP interpreter with decoupled GUI
+# Chipolata: a CHIP-8/SUPER-CHIP interpreter
 
 [![CI (main)](https://github.com/jon-axon/chipolata/actions/workflows/CI%20(main).yml/badge.svg?branch=main)](https://github.com/jon-axon/chipolata/actions/workflows/CI%20(main).yml)
 [![CI (dev)](https://github.com/jon-axon/chipolata/actions/workflows/CI%20(dev).yml/badge.svg?branch=development)](https://github.com/jon-axon/chipolata/actions/workflows/CI%20(dev).yml)
@@ -19,9 +19,9 @@ Chipolata was originally created as a learning project: an opportunity to get to
 
 The types of people who might be interested in Chipolata are:
 
-1) CHIP-8/retro gaming enthusiasts wanting to run a wide variety of CHIP-8 ROMs designed for a number of different history CHIP-8 interpreters/extensions in a single, intuitive, robust desktop application.
+1) CHIP-8/retro gaming enthusiasts wanting to run a wide variety of CHIP-8 ROMs designed for a number of different historic CHIP-8 interpreters/extensions in a single, intuitive, robust desktop application.
 2) Programmers  wanting to build a CHIP-8 front-end from an existing emulator library, rather than building the entire platform from scratch.  For example, the current Chipolata GUI is built using the [egui](https://github.com/emilk/egui) immediate mode UI library; building an alternative front-end as a way of learning or experimenting with one of the [many other  Rust UI libraries](https://www.areweguiyet.com/) could make for an excellent project.
-3) Programmers new to Rust or to emulation who would like to try making some enhancements or improvements to an existing codebase before/instead of taking-on an entire project of their own.  There are several  ways in which Chipolata can be extended (for example the addition of a debugging UI, which was always my intention) that may be of interest to someone.
+3) Programmers new to Rust or to emulation who would like to try making some enhancements or improvements to an existing codebase before/instead of taking-on an entire project of their own.  There are several  ways in which Chipolata can be extended (for example the addition of a debugging UI, which was always my intention) that may be of interest to someone.  Please feel free to take a look at the current open [Issues](https://github.com/jon-axon/chipolata/issues) for  inspiration.
 
 If you are looking for a very mature, fully-fledged web-based CHIP-8 IDE with associated tools and wider ecosystem then the de facto standard is [Octo](https://github.com/JohnEarnest/chip8Archive), and you may be better off looking there.
 
@@ -61,7 +61,7 @@ Any errors generated by the emulation engine are bubbled-up and displayed within
 
 # Emulator library overview
 
-The Chipolata library crate models the entire CHIP-8 virtual machine component-by-component, and favours the use of high-level abstractions over highly-optimised/in-lined code in an effort to prioritise easy of understanding and ease of use over the utmost efficiency.  Full, up-to-date `rustdoc` documentation is provided, and is linked within the [Further Reading](#further-reading) section.
+The Chipolata library crate models the entire CHIP-8 virtual machine component-by-component, and favours the use of high-level abstractions over highly-optimised/in-lined code in an effort to prioritise ease of understanding and ease of use over the utmost efficiency.  Full, up-to-date `rustdoc` documentation is provided, and is linked within the [Further Reading](#further-reading) section.
 
 ## Key features
 
@@ -93,6 +93,89 @@ Additionally, the following common configuration options are available in all em
 
 # Quick start
 
+**Please note**: at present, Chipolata is only available for Windows.  There is nothing intrinsic to Chipolata that precludes compilation for other platforms; I have simply not had the need or opportunity to look into cross-compilation yet.  This is on the to-do list!  For now, the remainder of this section assumes the reader is similarly running a 64-bit Windows architecture.
+
+## Running the Chipolata desktop app
+If you simply want to use Chipolata itself, the quickest way to get up-and-running is to download the latest binary from [Releases](https://github.com/jon-axon/chipolata/releases).  The zip file artefact attached to the release can be extracted to a location of your choosing, and contains the following:
+
+* The ***chipolata.exe*** file
+* A ***resources*** folder, containing:
+    * An ***options*** folder that contains a number of pre-defined option set .json files that can be loaded from the "Emulation Options" dialogue box within Chipolata
+    * A ***roms*** folder that contains a number of CHIP-8 and SUPER-CHIP ROMs (.ch8 files) available in the public domain, divided into the following category sub-folders:
+        * ***demos***   - largely non-interactive CHIP-8 demo programs
+        * ***games***   - interactive games 
+        * ***superchip***   - games requiring SUPER-CHIP emulation support (be sure to select the appropriate emulation mode within Chipolata)
+        * ***tests***   - test ROMs mainly of use to interpreter developers to ensure their implementation of CHIP-8 is behaving as intended
+
+Chipolata is configured to statically link the C runtime in addition to all its Cargo-added crate dependencies, so the .exe file has no additional dependencies that must be pre-installed on the host computer.
+
+##  Setting up a local Rust development environment
+
+If you wish to modify/enhance Chipolata, or simply wish to compile the binary for yourself direct from the source code, then you will need a local development environment with the Rust toolchain installed, and some form of code editor to work with.  A popular choice for the latter is ***Visual Studio Code*** (VS Code).  The steps to configure a VS Code-based Rust development environment are as follows:
+
+i) Install the Rust toolchain using `rustup`, by following the simple instructions on the [Install Rust](https://www.rust-lang.org/tools/install) page on the official Rust website.
+
+ii) Install VS Code from the [Visual Studio Code download page](https://code.visualstudio.com/Download).
+
+iii) Install the ***rust-analyzer extension*** for VS Code from within the Extensions view (`Ctrl+Shift+X`) by searching for 'rust-analyzer'.
+
+iv) If not already present on your computer, you will need to also [Install Git](https://git-scm.com/downloads) in order to be able to interact with the GitHub repo.
+
+Once installed, you can interact with the components of the Rust toolchain through a terminal window or the Command Prompt; if new to Rust you should familiarise yourself with these tools and commands (and in particular with `cargo`) before proceeding as they are fundamental to interacting with the project.
+
+## Working with the  Chipolata source code
+
+This section assumes you already have a GitHub account.  If not, please visit [Join GitHub](https://github.com/join) and sign up.
+
+If you would like to modify and recompile the Chipolata source code then you will need to first [Fork the Chipolata GitHub repo](https://github.com/jon-axon/chipolata/fork).
+
+Next you will need to clone your forked repo to your local environment to start working on it.  Please see [Cloning a repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) for instructions.
+
+Once you have a local copy of the repo you can start working on the source code within VS Code by selecting `File -> Open Folder` and choosing the corresponding local root `chipolata` folder (i.e. the folder containing the `cargo.toml` file).
+
+Useful Rust toolchain commands (executed within the Chipolata working directory) are:
+
+### Produce a debug build
+    cargo build
+This will create a .exe binary in the `chipolata\target\debug` folder.
+
+### Produce a release build
+    cargo build --release
+This will create an optimised .exe binary in the `chipolata\target\release` folder.
+
+### Run the Chipolata binary
+    cargo run
+This will build Chipolata in debug mode and run the executable for you.
+
+### Run the unit test suite
+    cargo test
+This will execute the entire unit test suite against the current codebase and report the results.
+
+### Run the unit test suite including ignored tests
+    cargo test -- --include-ignored
+This will execute the entire unit test suite including any tests that are ignored by default (typically those that involve performance/timings).
+
+### Rebuild `rustdoc` documentation
+    cargo doc
+This will recreate all the html documentation held in the `chipolata\target\doc` folder 
+structure.
+
+### Rebuild `rustdoc` documentation without dependencies
+    cargo doc --no-deps
+This will recreate the html documentation for the Chipolata library crate only (not the crates on which it is dependent).
+
+Use Git either on the command line or within the VS Code UI to commit changes and push them back to your forked GitHub repo.  Feel free to raise a Pull Request back to the `development` branch of the upstream [Chipolata repo](https://github.com/jon-axon/chipolata) if you've made changes that you think should be folded back in!
+
+## Using the Chipolata library as an external crate in a new project
+
+Chipolata is not published on [crates.io](https://crates.io) as I don't anticipate any demand for this.  However should you wish to use it - for example to write your own alternative UI - then you can still add a dependency to the Chipolata library crate by specifying the GitHub repository directly in your package's `cargo.toml` manifest as follows:
+
+    [dependencies]
+    chipolata = { git = "https://github.com/jon-axon/chipolata.git"}
+
+Once the dependency is added, please see the [Further Reading](#further-reading) section for links to the documentation to help you get started making use of the Chipolata library.
+
+In the unlikely event that it is beneficial for anyone for Chipolata to be published on crates.io (for example if somebody wants to publish their own crate that in turn has a dependency on Chipolata) then please let me know.
 
 If you have questions, please use [GitHub Discussions](https://github.com/jon-axon/chipolata/discussions).
 
@@ -101,15 +184,17 @@ If you have questions, please use [GitHub Discussions](https://github.com/jon-ax
 The Chipolata repo currently follows a traditional workflow with a `main` trunk branch and `development` long-lived feature branch (although it may be preferable at somepoint to replace this with a more lightweight [Git Flow](https://docs.github.com/en/get-started/quickstart/github-flow) approach).  Specifically, the branching strategy is as follows:
 
 * The `main` branch contains the latest release code (with appropriate tag assigned), and code may only be merged via Pull Request.
-* The `development` branch is used for staging sets of changes before the are ready to be merged into `main` as part of a new release.  Up until v1.0.0 I have been pushing changes directly into the `development` branch for convenience, however going forwards this branch should also only allow merges via Pull Request, and new code should instead by pushed to specific feature branches.
-* The `gh-pages` branch holds the HTML behind the [Chipolata GitHub Pages](https://jon-axon.github.io/chipolata/) site.  This branch should not be pushed-to directly, and is handled via the CI process (see below).
+* The `development` branch is used for staging sets of changes before they are ready to be merged into `main` as part of a new release.  Up until v1.0.0 I have been pushing changes directly into the `development` branch for convenience, however going forwards this branch should also only allow merges via Pull Request, and new code should instead by pushed to specific feature branches.
+* The `gh-pages` branch holds the HTML behind the [Chipolata GitHub Pages](https://jon-axon.github.io/chipolata/) site.  This branch should not be pushed-to directly, and is handled entirely via the CI process (see below).
 
 Continuous Integration [workflows](https://github.com/jon-axon/chipolata/actions) exist for pushes to both `main` and `development`:
 
 * The `CI (dev)` GitHub Action builds and runs the unit test suite against the `development` branch
 * The `CI (main)` GitHub Action builds and runs the unit test suite against the `main` branch, and then also rebuilds all the `rustdoc` documentation and pushes this to the `gh-pages` branch
 * The GitHub-generated `pages-build-deployment` workflow publishes changes to the `gh-pages` branch to the Chipolata GitHub Pages site, and so completes the automated documentation generation process whenever new code is pushed to `main`.
 
+Currently there is no automated release workflow; the CI process only goes as far as building, testing, and publishing documentation for new code pushed to `main`.  Creation of tags, releases, and uploading associated artefacts is a manual step.  Automating this is on the to-do list.
+
 Should you wish to contribute anything to Chipolata, please feel free to fork the repo and raise a PR back to the `development` branch!
 
 # Further reading