Initial commit

1 files changed, 110 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8e5f24e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,110 @@
+# picoarch - a libretro frontend designed for small screens and low power
+
+picoarch uses libpicofe and SDL to create a small frontend to libretro cores. It's designed for small (320x240 2.0-2.4") screen, low-powered devices like the Trimui Model S (PowKiddy A66).
+
+## Building
+
+The frontend can currently be built for the TrimUI Model S and Linux (useful for testing and debugging).
+
+First, fetch the repo with submodules:
+
+```
+git clone --recurse-submodules https://git.crowdedwood.com/picoarch
+```
+
+### Linux instructions
+
+To build picoarch itself, you need libSDL 1.2, libpng, and libasound. Different cores may need additional dependencies.
+
+After that, `make` bulids picoarch and all supported cores into this directory.
+
+### TrimUI instructions
+
+To build for TrimUI, you need to set up the [toolchain](https://git.crowdedwood.com/trimui-toolchain/about/) first.
+
+To build generic binaries:
+
+```
+make platform=trimui
+```
+
+If you want to build for MinUI, you need to install [libmmenu](https://github.com/shauninman/libmmenu) into the toolchain. Then:
+
+```
+make platform=trimui MINUI=1
+```
+
+`MINUI=1` will change save/config/system paths to match MinUI standards. If you just want to include mmenu, you can run:
+
+```
+make platform=trimui MMENU=1
+```
+
+### Other build options
+
+To debug:
+
+```
+make DEBUG=1
+```
+
+To build a specific supported core:
+
+```
+make gpsp_libretro.so
+```
+
+To clean a core so it will be built again:
+
+```
+make clean-gpsp
+```
+
+To completely clean the repo (will delete, pull, and patch all core repos from scratch)
+
+```
+make force-clean
+```
+
+Distribution builds can also be made for gmenunx and MinUI:
+
+```
+make platform=trimui dist-gmenu
+make platform=trimui MINUI=1 dist-minui
+```
+
+These will output a directory structure that can be moved onto the SD card into `pkg/gmenunx` or `pkg/MinUI`.
+
+To build profiles for profile-guided optimization:
+
+```
+make PROFILE=GENERATE
+```
+
+To apply the generated profiles:
+
+```
+make PROFILE=APPLY
+```
+
+PGO can lead to major speed improvements with some emulators.
+
+## Notes on cores
+
+In order to make development and testing easier, the Makefile will pull and build supported cores.
+
+A few common changes will need to be made when you add cores, since TrimUI is not a supported libretro platform. picoarch has a `patches/` directory containing needed changes to make cores work well in picoarch. Patches are applied in order after checking out the repository.
+
+Common changes include:
+
+- Adding a `platform=trimui` target to the core Makefile
+- Modifying `libretro_core_options.h` to shorten text, add manual line breaks, and change defaults for small screen / low power devices
+- Hiding unnecessary core options and forcing different defaults
+
+picoarch also keeps the running core name in a global variable. This can be used for:
+
+- Renaming buttons to match the core's system
+- Adding frameskip to make fast-forward faster
+- Displaying extra options or hiding unnecessary options
+
+Some features and fixes are also included in `patches` -- it would be best for them to be upstreamed eventually.