Update documentation.

davidgiven · davidgiven · commit 3440792ec97a · 2025-11-21T01:04:47.000+01:00
diff --git a/README.md b/README.md
@@ -14,32 +14,37 @@ the excellent [ImHex](https://imhex.werwolv.net/), which is substantially better
 What?
 -----
 
-The FluxEngine is a very cheap USB floppy disk interface capable of reading and
-writing exotic non-PC floppy disk formats. It allows you to use a conventional
-PC drive to accept Amiga disks, CLV Macintosh disks, bizarre 128-sector CP/M
-disks, and other weird and bizarre formats. (Although not all of these are
-supported yet. I could really use samples.)
-
-The hardware consists of a single, commodity part with a floppy drive
-connector soldered onto it. No ordering custom boards, no fiddly surface
-mount assembly, and no fuss: nineteen simpler solder joints and you're done.
-You can make one for $15 (plus shipping).
-
-Don't believe me? Watch the demo reel!
-
-<div style="text-align: center">
-<iframe width="373" height="210" src="https://www.youtube.com/embed/m_s1iw8eW7o" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
-</div>
-
-**New!** The FluxEngine client software now works with
-[Greaseweazle](https://github.com/keirf/Greaseweazle/wiki) and
-[Applesauce](https://applesaucefdc.com/) hardware. So, if you can't find a PSoC5
-development kit, or don't want to use the Cypress Windows tools for programming
-it, you can use one of these instead. Very nearly all FluxEngine features are
-available with the Greaseweazle and it works out-of-the box; the Applesauce is a
-bit less supported but still works. See the [dedicated Greaseweazle
-documentation page](doc/greaseweazle.md) or the [Applesauce
-page](doc/applesauce.md) for more information.
+FluxEngine is two things:
+
+- Firstly: the [FluxEngine hardware](doc/building-hardware.md) is a very cheap USB floppy disk interface capable of
+  reading and
+  writing exotic non-PC floppy disk formats. It allows you to use a conventional
+  PC drive to accept Amiga disks, CLV Macintosh disks, bizarre 128-sector CP/M
+  disks, and other weird and bizarre formats. (Although not all of these are
+  supported yet. I could really use samples.)
+
+  The hardware consists of a single, commodity part with a floppy drive
+  connector soldered onto it. No ordering custom boards, no fiddly surface
+  mount assembly, and no fuss: nineteen simpler solder joints and you're done.
+  You can make one for $15 (plus shipping).
+
+  Don't believe me? Watch the demo reel!
+
+  <div style="text-align: center">
+    <iframe width="373" height="210" src="https://www.youtube.com/embed/m_s1iw8eW7o" frameborder="0"
+            allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+  </div>
+
+- Secondly: the [FluxEngine software](doc/building-client.md) is a cross-platform set of tools for reading, writing and
+  processing floppy disk magnetic flux information.
+  It works on the FluxEngine hardware (described above), the
+  [Greaseweazle](https://github.com/keirf/Greaseweazle/wiki), and to a limited extent the
+  [Applesauce](https://applesaucefdc.com/). You can also use it standalone for working with either flux dumps or simple
+  sector images of disks.
+
+  See the [dedicated Greaseweazle
+  documentation page](doc/greaseweazle.md) or the [Applesauce
+  page](doc/applesauce.md) for more information about using the FluxEngine client with these devices.
 
 Where?
 ------
@@ -52,35 +57,37 @@ How?
 This page was getting kinda unwieldy so I've broken it up. Please consult the
 following friendly articles:
 
-  - [Frequently asked questions](doc/faq.md) ∾ but why...? ∾ does it...? ∾ can it...?
-  
-  - [How the FluxEngine works](doc/technical.md) ∾ nitty gritty of the
-    sampler/sequencer hardware ∾ useful links on floppy drives ∾ why I'm not
-    using an Arduino/STM32/ESP32/Raspberry Pi
+- [Frequently asked questions](doc/faq.md) ∾ but why...? ∾ does it...? ∾ can it...?
+
+- [How the FluxEngine works](doc/technical.md) ∾ nitty gritty of the
+  sampler/sequencer hardware ∾ useful links on floppy drives ∾ why I'm not
+  using an Arduino/STM32/ESP32/Raspberry Pi
+
+- [Building the FluxEngine software](doc/building-client.md) ∾ dependencies ∾ build commands ∾ installation
+
+- [Making the FluxEngine hardware](doc/building-hardware.md) ∾ what parts you need ∾ building it ∾
+  setting up the toolchain ∾ compiling the firmware ∾ programming the board
 
-  - [Making a FluxEngine](doc/building.md) ∾ what parts you need ∾ building it ∾
-    setting up the toolchain ∾ compiling the firmware ∾ programming the board
+- [Using a FluxEngine](doc/using.md) ∾ what to do with your new hardware ∾
+  flux files and image files ∾ knowing what you're doing
 
-  - [Using a FluxEngine](doc/using.md) ∾ what to do with your new hardware ∾
-    flux files and image files ∾ knowing what you're doing
+- [Using Greaseweazle hardware with the FluxEngine client
+  software](doc/greaseweazle.md) ∾ what works ∾ what doesn't work ∾ where to
+  go for help
 
-  - [Using Greaseweazle hardware with the FluxEngine client
-    software](doc/greaseweazle.md) ∾ what works ∾ what doesn't work ∾ where to
-    go for help
+- [Configuring for your drive](doc/drives.md) ∾ but I don't have a 80 track
+  drive! ∾ reading and writing 40 track disks ∾ Shugart and Apple II
 
-  - [Configuring for your drive](doc/drives.md) ∾ but I don't have a 80 track
-    drive! ∾ reading and writing 40 track disks ∾ Shugart and Apple II
+- [Direct filesystem access](doc/filesystem.md) ∾ imaging files is a pain
+  ∾ accessing files directly ∾ features and limitation ∾ it works on disk
+  images too, you say?
 
-  - [Direct filesystem access](doc/filesystem.md) ∾ imaging files is a pain
-    ∾ accessing files directly ∾ features and limitation ∾ it works on disk
-    images too, you say?
-    
-  - [Troubleshooting dubious disks](doc/problems.md) ∾ it's not an exact
-    science ∾ the sector map ∾ clock detection and the histogram
+- [Troubleshooting dubious disks](doc/problems.md) ∾ it's not an exact
+  science ∾ the sector map ∾ clock detection and the histogram
 
-  - [Disk densities](doc/driveresponse.md) ∾ what's the difference between an HD
-    and DD disk? ∾ you can't do that with that ∾ measuring your drive's ability to
-    work with exotic formats ∾ I think my drive is broken
+- [Disk densities](doc/driveresponse.md) ∾ what's the difference between an HD
+  and DD disk? ∾ you can't do that with that ∾ measuring your drive's ability to
+  work with exotic formats ∾ I think my drive is broken
 
 Which?
 ------
@@ -148,22 +155,22 @@ choices because they can store multiple types of file system.
 
 ### Notes
 
-  - IBM PC disks are the lowest-common-denominator standard. A number of other
-    systems use this format in disguise (the Atari ST, late-era Apple
-    machines, Acorn). FluxEngine supports both FM and MFM disks, although you
-    have to tell it which one. If you have an unknown disk, try this; you may
-    get something. Then [tell me about
-    it](https://github.com/davidgiven/fluxengine/issues/new).
-
-  - Not many formats support writing yet. That's because I need actual,
-    physical hardware to test with in order to verify it works, and I only
-    have a limited selection. (Plus a lot of the write code needs work.)
-    There hasn't been a lot of demand for this yet; if you have a pressing
-    need to write weird disks, [please
-    ask](https://github.com/davidgiven/fluxengine/issues/new). I haven't
-    implemented write support for PC disks because they're boring and I'm lazy,
-    and also because they vary so much that figuring out how to specify them
-    is hard.
+- IBM PC disks are the lowest-common-denominator standard. A number of other
+  systems use this format in disguise (the Atari ST, late-era Apple
+  machines, Acorn). FluxEngine supports both FM and MFM disks, although you
+  have to tell it which one. If you have an unknown disk, try this; you may
+  get something. Then [tell me about
+  it](https://github.com/davidgiven/fluxengine/issues/new).
+
+- Not many formats support writing yet. That's because I need actual,
+  physical hardware to test with in order to verify it works, and I only
+  have a limited selection. (Plus a lot of the write code needs work.)
+  There hasn't been a lot of demand for this yet; if you have a pressing
+  need to write weird disks, [please
+  ask](https://github.com/davidgiven/fluxengine/issues/new). I haven't
+  implemented write support for PC disks because they're boring and I'm lazy,
+  and also because they vary so much that figuring out how to specify them
+  is hard.
 
 If you have samples of weird disks, and want to send them to me --- either
 FluxEngine, Kryoflux or Catweasel dumps, or (even better) actually physically
diff --git a/doc/building-client.md b/doc/building-client.md
@@ -0,0 +1,48 @@
+Building the client
+=====================
+
+The client software is where the intelligence, such as it is, is. It doesn't need the FluxEngine hardware, and will work
+either with it, a Greaseweazle, or (to a limited extent) an Applesauce.
+
+The CLI is pretty generic libusb stuff and should build and run on pretty much anything; the GUI is based on ImHex and
+will work wherever ImHex does. Support platforms for the FluxEngine client include Windows, Linux and OSX as
+well, although on Windows it'll need MSYS2 and mingw32. You'll need to
+install some support packages. **You will need to check out git with submodules enabled.**
+
+  - For Linux with Ubuntu/Debian:
+    `libudev-dev` `libsqlite3-dev` `protobuf-compiler` `libfmt-dev`
+    `libprotobuf-dev` `libmagic-dev` `libmbedtls-dev`
+    `libcurl4-openssl-dev` `libmagic-dev` `nlohmann-json3-dev`
+    `libdbus-1-dev` `libglfw3-dev` `libmd4c-dev` `libfreetype-dev`
+    `libcli11-dev` `libboost-regex-dev`
+  - For OSX with Homebrew:
+    `sqlite` `pkg-config` `libusb` `protobuf` `fmt` `make` `coreutils`
+    `dylibbundler` `libjpeg` `libmagic` `nlohmann-json` `cli11` `boost`
+    `glfw3` `md4c` `ninja` `python` `freetype2` `mbedtls`
+  - For Windows with MSYS and pacboy:
+    `protobuf:p` `pkgconf:p` `curl-winssl:p` `file:p` `glfw:p` `mbedtls:p`
+    `sqlite:p` `freetype:p` `boost:p` `gcc:p` `binutils:p` `nsis:p`
+    `abseil-cpp:p`
+
+There may be mistakes here --- please [get in
+touch](https://github.com/davidgiven/fluxengine/issues/new) if I've missed
+anything.
+
+Windows and Linux (and other Unixes) build by just doing `make`. OSX builds by
+doing `gmake` (we're using a feature which the elderly default make in OSX
+doesn't have). Parallel builds will be detected automatically; do `-j1` if for some
+reason you don't want one.
+You should end up with some executables in the current directory. The command line version
+is called `fluxengine` or `fluxengine.exe` depending on your platform,
+and the ImHex-based GUI will be `fluxengine-gui` or `fluxengine-gui.exe`.
+They have
+minimal dependencies and you should be able to put it anywhere. The other
+binaries may also be of interest.
+
+Potential issues:
+
+  - Complaints about a missing `libudev` on Windows? Make sure you're using the
+  mingw Python rather than the msys Python.
+
+If it doesn't build, please [get in
+touch](https://github.com/davidgiven/fluxengine/issues/new).
diff --git a/doc/building-hardware.md b/doc/building-hardware.md
@@ -194,50 +194,6 @@ until the light stays solidly on. Now you should be able to acquire
 the port and proceed normally.
 
 
-## Building the client
-
-The client software is where the intelligence, such as it is, is. It's pretty
-generic libusb stuff and should build and run on Windows, Linux and OSX as
-well, although on Windows it'll need MSYS2 and mingw32. You'll need to
-install some support packages.
-
-  - For Linux with Ubuntu/Debian:
-	`libusb-1.0-0-dev`, `libsqlite3-dev`, `zlib1g-dev`,
-	`libudev-dev`, `protobuf-compiler`, `libwxgtk3.0-gtk3-dev`,
-	`libfmt-dev`, `python3`. `ninja-build`
-  - For Linux with Fedora/Red Hat:
-    `git`, `make`, `gcc`, `gcc-c++`, `xxd`, `protobuf-compiler`,
-    `protobuf-devel`, `fmt-devel`, `systemd-devel`, `wxGTK3-devel`,
-    `libsqlite3x-devel`, `ninja-build`
-  - For OSX with Homebrew: `libusb`, `pkg-config`, `sqlite`,
-    `protobuf`, `truncate`, `wxwidgets`, `fmt`. `ninja`
-  - For Windows with WSL: `protobuf-c-compiler` `protobuf-devel` `fmt-devel`
-  `systemd-devel` `sqlite-devel` `wxGTK-devel` `mingw32-gcc` `mingw32-gcc-c++`
-  `mingw32-zlib-static` `mingw32-protobuf-static` `mingw32-sqlite-static`
-  `mingw32-wxWidgets3-static` `mingw32-libpng-static` `mingw32-libjpeg-static`
-  `mingw32-libtiff-static` `mingw32-nsis png2ico` `ninja-build`
-
-These lists are not necessarily exhaustive --- please [get in
-touch](https://github.com/davidgiven/fluxengine/issues/new) if I've missed
-anything.
-
-Windows and Linux (and other Unixes) build by just doing `make`. OSX builds by
-doing `gmake` (we're using a feature which the elderly default make in OSX
-doesn't have). Remember to add an appropriate `-j` option for a parallel build.
-You should end up with some executables in the current directory, one of which
-is called `fluxengine` or `fluxengine.exe` depending on your platform. It has
-minimal dependencies and you should be able to put it anywhere. The other
-binaries may also be of interest.
-
-Potential issues:
-
-  - Complaints about a missing `libudev` on Windows? Make sure you're using the
-  mingw Python rather than the msys Python.
-
-If it doesn't build, please [get in
-touch](https://github.com/davidgiven/fluxengine/issues/new).
-
-
 ## Connecting it up
 
 You should now have a working board, so it's time to test it.
