emux/README

Emux <https://github.com/sronsse/emux>

These are the release notes for Emux and tell you what this project is about,
how to build it, how to install it, and how to run it.

WHAT IS EMUX?

  Emux is a cross-platform emulator project with a goal of emulating multiple
  kinds of machines related to gaming, such as consoles or arcades. Its
  philosophy is very much inspired by the Linux kernel (hence the name), which
  brilliantly manages to support multiple machines while keeping drivers
  entirely platform-independent. Emux is designed in the same way, keeping a
  code base of CPUs and controllers separate from machines.

  It is distributed under the GNU General Public License v2 - see the
  accompanying COPYING file for more details.

SOFTWARE DEPENDENCIES

  Emux can use different audio and video/input frontends. At the time of
  writing, SDL (standalone and OpenGL) and libcaca are supported for video/input
  and only SDL for audio. During the configuration step, you may select the
  frontends to be included in the build. The configure script will complain if
  these libraries are not found. Note: no particular dependency is required in
  order to build libretro implementations.

  Emux can now use libroxml - a tiny XML parsing library - in order to read
  input configuration files. This optional library is typically not part of
  standard distributions and needs to be downloaded, built, and installed on
  your host machine. The libroxml project is developed by Tristan Lelong and can
  be found at the following location:
  http://www.libroxml.net/

  If advanced configuration of Emux is needed, kconfig-frontends needs to be
  installed on your host machine. Linux developers should be very familiar with
  menuconfig, a convenient menu-driven user interface allowing the configuration
  of the Linux kernel. kconfig-frontends brings the ability to use these same
  tools for any project other than the Linux kernel, by packaging these tools
  apart from the kernel so that they can ship independently. However, the
  project aims at tracking changes made to kconfig in the kernel development
  tree, to ensure they benefit to anyone using kconfig-frontends. The current
  package maintainer is Yann E. Morin, and the project is hosted at:
  http://ymorin.is-a-geek.org/projects/kconfig-frontends

  Here are the software dependencies for a full-featured build of Emux:
  - autoconf
  - automake
  - kconfig-frontends (optional)
  - libcaca-dev (optional)
  - libroxml (optional)
  - libsdl2-dev (optional)
  - pkg-config

CONFIGURING EMUX

  Once all software dependencies are taken care of, navigate to the Emux sources
  folder from a terminal and execute the following command to configure
  Emux:
    ./configure

  This step will build a default Emux configuration (all_defconfig). If advanced
  configuration is needed (in order to add/remove support for various
  components), you may use the following command provided that kconfig-frontends
  is properly installed on your host machine:
    ./configure MENU=<conf> (ie. use ./configure MENU=mconf for kconfig-mconf).

  This should bring up a menuconfig interface where you can specify frontends,
  machines, CPUs, and controllers to build. If you need help with one particular
  item, press 'h' to show a basic description of your selection.

  All supported machines also come with a default configuration (all stored
  under mach/configs). You can select a particular configuration by specifying
  it on the configure command line:
    ./configure CONF=<defconfig> (ie. ./configure CONF=nes_defconfig)

  Note: standard rules apply if you need to cross-compile Emux.

BUILDING EMUX

  After completion of the configuration step, building is as easy as executing
  the following command:
    make

  By default, no particular optimization level is selected for compilation.
  CFLAGS can be appended to the make command for this purpose.
  Example:
    make CFLAGS=-O2

  As the standard GNU make utility is used, you may append the -j<n> option
  to speed up the build process, where n is your number of execution units.
  Example:
    make -j16

INSTALLING EMUX

  If nothing went wrong during the build process, Emux can be installed on your
  system by executing the following command:
    make install

RUNNING EMUX

  Once installed on your system, you should now be able to run Emux. Here is a
  list of the available options:
  --audio=string        Selects audio frontend
  --config-dir=string   Path to config directory
  --cycles=int          Sets number of machine cycles to emulate
  --help                Display this help and exit
  --log-level=int       Specifies log level (0 to 3)
  --machine=string      Selects machine to emulate
  --no-sync             Disables emulation syncing
  --sampling-rate=int   Sets audio sampling rate
  --save-dir=string     Path to save directory
  --scale=int           Applies a screen scale ratio
  --system-dir=string   Path to system directory
  --video=string        Selects video frontend

  If you would like to run INVADERS (CHIP-8) using libcaca for graphics, SDL for
  audio, and use the default window size, the command would be:
    emux --machine=chip8 --video=caca --audio=sdl INVADERS

  Certain machines also have a subset of options. These are displayed below the
  main ones described above.

  Note: when configuring the project, you may also specify a default command
  line, with the option of replacing, extending, or forcing it.

LIBRETRO

  RetroArch is an open-source project that makes use of a powerful development
  interface called Libretro. Libretro is an interface that allows you to make
  cross-platform applications that can use rich features such as OpenGL,
  cross-platform camera support, location support, and more in the future.

  Emux can also be built as separate libretro cores to be loaded by libretro
  frontends such as RetroArch. After navigating to libretro/, you may build any
  machine using the following command, replacing "platform" and "machine"
  accordingly:
    make -f Makefile.platform MACHINE=machine

  Here is an example of how to build the Sega Master System core for Wii:
    cd libretro/
    make -f Makefile.wii MACHINE=sms

EMSCRIPTEN

  Emscripten is an LLVM to JavaScript compiler. It takes LLVM bytecode (which
  can be generated from C/C++ using Clang, or any other language that can be
  converted into LLVM bytecode) and compiles that into JavaScript, which can be
  run on the web (or anywhere else JavaScript can run).

  After setting up an Emscripten environment on your development machine, the
  following commands (which include optimization flags) will allow an
  HTML/JavaScript version of Emux to be built and run within your favorite web
  browser:
    emconfigure ./configure
    emmake make CFLAGS=-O2
    mv emux emux.bc
    emcc -O2 emux.bc -o emux.html

  Note: the --preload-file Emscripten directive allows files to be packaged as
  part of the generated output (helpful when bundling ROMs). You may also need
  to specify a default command line as described earlier, as Emscripten will not
  allow it to be entered via the produced HTML/JavaScript (at least without
  extra JavaScript modifications).

HELP
  If you need help with Emux, or would like to report bugs (as long as these are
  detailed), feel free to contact me directly at [email protected]. Emux is
  open-source, so if you would like to contribute to the project, you may
  contact me as well.