Documentation update.

INSTALL.md

@@ -21,19 +21,36 @@ The code has a few dependencies. For building, you'll need CMake and development
 
 **Installing dependencies:**
 
-**On Debian/Ubuntu:**
+**On Debian/Ubuntu**
+
 All of the required packages can be installed with apt-get:
 ```
-sudo apt-get install build-essential cmake libsdl2-dev libfreeimage-dev libfreetype6-dev libcurl4-openssl-dev libpugixml-dev rapidjson-dev libasound2-dev libvlc-dev libgl1-mesa-dev
+sudo apt-get install build-essential git cmake libsdl2-dev libfreeimage-dev libfreetype6-dev libcurl4-openssl-dev libpugixml-dev rapidjson-dev libasound2-dev vlc libvlc-dev libgl1-mesa-dev
 ```
 
-**On Fedora:**
+**On Fedora**
-For this operating system, use dnf (with rpmfusion activated):
+
+First add the RPM Fusion repository which is required for VLC. Go to [https://rpmfusion.org/Configuration](https://rpmfusion.org/Configuration) and download the .rpm package for the free repository, then install it such as this:
+
 ```
-sudo dnf install cmake SDL2-devel freeimage-devel freetype-devel curl-devel rapidjson-devel alsa-lib-devel vlc-devel mesa-libGL-devel
+sudo dnf install ./rpmfusion-free-release-33.noarch.rpm
 ```
 
-**On FreeBSD:**
+Then use dnf to install all the required packages:
+```
+sudo dnf install gcc-c++ cmake SDL2-devel freeimage-devel freetype-devel curl-devel pugixml-devel rapidjson-devel alsa-lib-devel mesa-libGL-devel vlc vlc-devel
+```
+
+**On Manjaro**
+
+Use pacman to install all the required packages:
+
+```
+pacman -S gcc make cmake pkgconf sdl2 freeimage freetype2 pugixml rapidjson vlc
+```
+
+**On FreeBSD**
+
 Use pkg to install the dependencies:
 ```
 pkg install git pkgconf cmake sdl2 freeimage pugixml rapidjson vlc
@@ -41,7 +58,8 @@ pkg install git pkgconf cmake sdl2 freeimage pugixml rapidjson vlc
 
 Clang/LLVM and cURL should already be installed in the base OS image.
 
-**On NetBSD:**
+**On NetBSD**
+
 Use pkgin to install the dependencies:
 ```
 pkgin install git cmake pkgconf SDL2 freeimage pugixml rapidjson vlc
@@ -49,7 +67,8 @@ pkgin install git cmake pkgconf SDL2 freeimage pugixml rapidjson vlc
 
 NetBSD ships with GCC by default, and although you should be able to install and use Clang/LLVM, it's probably easier to just stick to the default compiler environment.
 
-**On OpenBSD:**
+**On OpenBSD**
+
 Use pkg_add to install the dependencies:
 ```
 pkg_add cmake pkgconf sdl2 freeimage vlc
@@ -78,7 +97,7 @@ make
 make install
 ```
 
-**Cloning and compiling ES-DE:**
+**Cloning and compiling ES-DE**
 
 To clone the source repository, run the following:
 
@@ -161,7 +180,7 @@ cmake -DCMAKE_INSTALL_PREFIX=/opt .
 
 It's important to know that this is not only the directory used by the install script, the CMAKE_INSTALL_PREFIX variable also modifies code inside ES used to locate the required program resources. So it's necessary that the install prefix corresponds to the location where the application will actually be installed.
 
-**Compilers:**
+**Compilers**
 
 Both Clang/LLVM and GCC work fine for building ES.
 
@@ -244,7 +263,7 @@ A theme is not mandatory to start the application, but ES will be basically usel
 
 The home directory will always take precedence, and any resources or themes located there will override the ones in the installation path or in the path of the ES executable.
 
-**Creating .deb and .rpm packages:**
+**Creating .deb and .rpm packages**
 
 Creation of Debian .deb packages is enabled by default, simply run `cpack` to generate the package:
 
@@ -259,7 +278,17 @@ CPackDeb: - Generating dependency list
 CPack: - package: /home/myusername/emulationstation-de/emulationstation-de-1.0.0.deb generated.
 ```
 
-The package can now be installed using a package manager, for example `dpkg`.
+You may like to check that the dependencies look fine, as they're automatically generated by CMake:
+
+```
+dpkg -I -/emulationstation-de-1.0.0.deb
+```
+
+The package can now be installed using a package manager, for example apt:
+
+```
+sudo apt install ./emulationstation-de-1.0.0.deb
+```
 
 For RPM packages, remove the comment in the `CMakeLists.txt` accordingly, from:
 
@@ -273,12 +302,25 @@ SET(CPACK_GENERATOR "RPM")
 
 Then simply run `cpack`.
 
-To be able to generate RPM packages on a Debian system such as Ubuntu, install the `rpm` package first:
+On Fedora, you need to install rpmbuild before this command can be run though:
-
 ```
-sudo apt-get install rpm
+sudo dnf install rpm-build
 ```
 
+After the package generation you can check that the metadata looks fine using this command:
+```
+rpm -qi ./emulationstation-de-1.0.0.rpm
+```
+
+And to see the automatically generated dependency requirements, run this:
+```
+rpm -q --requires ./emulationstation-de-1.0.0.rpm
+```
+
+And of course, you can also install the package:
+```
+sudo dnf install ./emulationstation-de-1.0.0.rpm
+```
 
 ## Building on macOS
 
@@ -518,15 +560,13 @@ add_custom_command(TARGET EmulationStation POST_BUILD COMMAND ${CMAKE_INSTALL_NA
 
 ## Building on Windows
 
-This is a strange legacy operating system. However it's still popular, so we need to support it.
+At the moment I have only built the software using GCC on Windows, but I aim to get Clang/LLVM working at a later date.
 
 I did a brief evaluation of the Microsoft Visual C++ compiler (MSVC) but as far as I'm concerned it's an abomination so I won't cover it here and it won't be supported.
 
 The OpenGL library shipped with Windows is unfortunately garbage, so the OpenGL Extension Wrangler (GLEW) library needs to be used as well to provide shader support. Its installation is explained below.
 
-At the moment I have only built the software using GCC on Windows, but I aim to get Clang/LLVM working at a later date.
+Anyway, here's a quite long summary of how to get a build environment up and running on Windows.
-
-Anyway, here's a (not so) brief summary of how to get a build environment up and running on Windows.
 
 **Install Git, CMake, MinGW and your code editor:**
 
@@ -534,9 +574,9 @@ Anyway, here's a (not so) brief summary of how to get a build environment up and
 
 [https://cmake.org/download](https://cmake.org/download)
 
-[https://gnutoolchains.com/mingw64](https://gnutoolchains.com/mingw64)
+[https://jmeubank.github.io/tdm-gcc](https://jmeubank.github.io/tdm-gcc)
 
-Make a copy of `mingw64/bin/mingw32-make` to `make` just for convenience and make sure that the necessary paths are defined for the PATH environmental variable.
+After installation, make a copy of `TDM-GCC-64/bin/mingw32-make` to `make` just for convenience.
 
 I won't get into the details on how to configure Git, but there are many resources available online to support with this. The `Git Bash` shell is very useful though as it's somewhat reproducing a Unix environment using MinGW/MSYS.
 
@@ -544,31 +584,7 @@ Install your editor of choice, I use [VSCode](https://code.visualstudio.com).
 
 It's strongly recommended to set line breaks to Unix-style (line feed only) directly in the editor, although it can also be configured in Git for conversion during commit. The source code for EmulationStation-DE only uses Unix-style line breaks.
 
-**Enable pretty printing for GDB:**
+Note that most GDB builds for Windows have broken Python support so that pretty printing won't work. The MinGW installation recommended above should work fine though.
-
-This is useful for displaying `std::string` values for example.
-
-Adjust your paths accordingly, the below are just examples of course.
-
-Save a file to
-C:\Programming\mingw64\bin\pp.gdb with the following contents:
-
-```
-python
-import sys
-sys.path.insert(0, 'c:/Programming/mingw64/share/gcc-9.1.0/python/libstdcxx/v6')
-from printers import register_libstdcxx_printers
-register_libstdcxx_printers (None)
-end
-```
-
-If using VSCode, add the following line to launch.json:
-
-`"miDebuggerArgs": "-x c:/programming/mingw64/bin/pp.gdb",`
-
-An equivalent setup should be possible on other code editors as well.
-
-Note that most GDB builds for Windows have broken Python support so that pretty printing won't work. The MinGW installation recommended in the previous step should work fine though.
 
 **Download the dependency packages:**
 
@@ -584,6 +600,8 @@ SDL2\
 libVLC\
 [https://ftp.lysator.liu.se/pub/videolan/vlc](https://ftp.lysator.liu.se/pub/videolan/vlc)
 
+For VLC, download both the binary distribution for win64 as well as the source code package.
+
 Uncompress the files for the above packages to a suitable directory, for example C:\Programming\Dependencies\
 
 GLEW\
@@ -598,14 +616,14 @@ unzip glew-2.1.0.zip
 cd glew-2.1.0
 make
 ```
-You will probably see a huge amount of compile warnings, and the glewinfo.exe tool may fail to build, but we don't need it so it's not an issue.
+You will probably see a huge amount of compiler warnings, and the glewinfo.exe tool may fail to build, but we don't need it so it's not an issue.
 
 The following packages are not readily available for Windows either, so clone the repos and build them yourself:
 
 [FreeType](https://www.freetype.org)
 ```
 git clone git://git.savannah.gnu.org/freetype/freetype2.git
-git checkout VER-2-10-2
+git checkout VER-2-10-4
 mkdir build
 cd build
 cmake -G "MinGW Makefiles" -DBUILD_SHARED_LIBS=ON ..
@@ -677,11 +695,12 @@ libgcc_s_seh-1.dll    (located in Git MinGW/MSYS under /mingw/bin/)
 libpugixml.dll
 libSDL2main.a
 libssl-1_1-x64.dll        (from the OpenSSL package, located in Git MinGW under /mingw/bin/)
-libstdc++-6.dll
+libstdc++-6.dll           (from the MinGW/bin folder)
 libvlc.dll
 libvlccore.dll
-libwinpthread-1.dll    (located in Git MinGW under /mingw/bin/)
+libwinpthread-1.dll       (from the MinGW/bin folder)
 SDL2.dll
+vcomp140.dll              (From Visual C++ Redistributable for Visual Studio 2015, 32-bit version)
 ```
 
 The files from the MinGW installation must correspond to the version used to compile the binary.
@@ -703,7 +722,7 @@ codec\libavcodec_plugin.dll
 codec\libx264_plugin.dll
 codec\libx265_plugin.dll
 logger\libconsole_logger_plugin.dll
-text_renderer\libfreetype_plugin.dll
+text_renderer\libfreetype_plugin.dll        ????? remove ?????
 video_chroma\libswscale_plugin.dll
 video_output\libvmem_plugin.dll
 ```

README.md

@@ -7,16 +7,20 @@ As the name implies, this software is intended to be used on desktop computers.
 
 Although there are multiple forks of EmulationStation in existence, the goal of this edition is to make the software as easy as possible to install and use as a standalone application, and to suppport the major desktop operating systems, i.e. Unix/Linux, macOS and Windows. Since it's intended to be used as a desktop application rather than as the primary interface for the computer, there are no plans to provide system administration utilities or control of emulator settings from within ES-DE.
 
-The current version 1.0 has been tested on the following operating systems:
+The current version 1.0 has been tested on the following operating systems (all for the x86 architecture):
 
-* Kubuntu 20.04
+* Ubuntu 20.04
-* FreeBSD 12.2 (x86)
+* Linux Mint 20
-* NetBSD 9.1 (x86)
+* Manjaro
-* OpenBSD 6.8 (x86) (limited testing only)
+* Fedora 33 Workstation
+* FreeBSD 12.2
+* NetBSD 9.1
+* OpenBSD 6.8 (limited testing only)
+* macOS 11 "Big Sur" (limited testing only)
 * macOS 10.15 "Catalina" (limited testing only)
 * macOS 10.11 "El Capitan"
-* Windows 10 (x86)
+* Windows 10
-* Windows 8.1 (x86)
+* Windows 8.1
 
 At the moment Raspberry Pi is not supported, but this is planned for future releases. It may still be possible to compile and run ES-DE on this device, but as of v1.0 it's not actively used during development and therefore not tested.
 

USERGUIDE.md

@@ -1,6 +1,6 @@
 # EmulationStation Desktop Edition (ES-DE) v1.0 - User Guide
 
-**Note:** This document is intended as a quick start guide, for more in-depth information and details on how to compile EmulationStation and perform more advanced configuration, please refer to the [INSTALL.md](INSTALL.md) document.
+**Note:** This document is intended as a quick start guide as well as a reference for the user interface settings and functionality. For more in-depth information and details on how to compile EmulationStation and perform more advanced configuration, please refer to the [INSTALL.md](INSTALL.md) document.
 
 Table of contents:
 
@@ -8,39 +8,80 @@ Table of contents:
 
 ## Getting started
 
-Getting started with EmulationStation is very easy, just make sure to install the software properly, either manually as built from source code or using one of the supplied packages. On Windows you'll use the installer instead of a package.
+Getting started with EmulationStation is easy, just make sure to install the software properly, either manually as built from source code or using one of the supplied packages. On Windows and macOS you'll use the installer instead of a package.
 
-The installation procedure will not be covered here as it differs between operating system, so please refer to your operating system documentation for information regarding this topic. EmulationStation Desktop Edition is currently supplied as .deb and .rpm packages for Linux and as a standard NSIS installer for Windows.
+The following operating systems have been tested (all for the x86 architecture):
 
-The following operating systems have been tested:
+* Ubuntu 20.04
-
+* Linux Mint 20
-* Kubuntu 20.04
+* Manjaro
-* FreeBSD 12.2 (x86)
+* Fedora 33 Workstation
-* NetBSD 9.1 (x86)
+* FreeBSD 12.2
-* OpenBSD 6.8 (x86) (limited testing only)
+* NetBSD 9.1
+* OpenBSD 6.8 (limited testing only)
+* macOS 11 "Big Sur" (limited testing only)
 * macOS 10.15 "Catalina" (limited testing only)
 * macOS 10.11 "El Capitan"
-* Windows 10 (x86)
+* Windows 10
-* Windows 8.1 (x86)
+* Windows 8.1
+
+
+The installation procedure is just covered briefly here and may differ a bit for your specific operating system, so in case of problems refer to your system documentation.
+
+**Installing a Linux .deb package**
+
+Thes .deb package is used for Linux distributions based on Debian, such as Ubuntu, Linux Mint etc.
+Running the following should install ES-DE and resolve any dependencies:
+
+```
+sudo apt install ./emulationstation-de-1.0.0.deb
+```
+
+**Installing a Linux .rpm package**
+
+On Fedora you run this command to install ES-DE, which should automatically resolve all dependencies:
+
+```
+sudo dnf install ./emulationstation-de-1.0.0.rpm
+```
+
+Note that this requires the RPM Fusion repository as there's a depedency on VLC, which is not part of the standard operating system repo. See [INSTALL.md](INSTALL.md#building-on-unix) for details on how to add this.
+
+**Installing on macOS and Windows**
+
+There's not really much to say about these operating systems, just install ES-DE as you would any other application. On maCOS it's via the .dmg drag-and-drop installer, and on Windows it's just a normal application installer (basically next, next, finish).
+
+**On first application startup**
 
 Upon first startup, ES-DE will create its home directory, by default the location is ~/.emulationstation.
 
-On Unix this defaults to /home/\<username\>/.emulationstation/, on macOS /Users/\<username\>/.emulationstation/ and on Windows C:\Users\\<username>\\.emulationstation\
+On Unix this means /home/\<username\>/.emulationstation/, on macOS /Users/\<username\>/.emulationstation/ and on Windows C:\Users\\<username>\\.emulationstation\
 
-A settings file, **es_settings.cfg** will be generated with all the default settings, and a **es_systems.cfg** file will also be copied from the program resource folder. This file contains the game ROM and emulator settings and can be modified if needed. For information on how to do this, refer to the [INSTALL.md](INSTALL.md) document.
+**Note:** As of ES-DE v1.0 there is no internationalization support, so you would always need to supply the English directory name for your home directory, which is by the way always the real physical name on the file system. For instance in macOS, /Users/leon will be required instead of /Användare/leon which is what's shown inside the operating system for a Swedish localized installation. But using the tilde home symbol '~' is a workaround for this, and it's recommended to always use it for any ES-DE configuration settings that require a path to your home directory as it removes any confusion regarding localized home directory paths.
 
-**Note:** On Unix it's assumed that RetroArch is using the default configuration directory location, i.e. the cores should be located in ~/.config/retroarch/cores. If you've installed RetroArch via a Snap package, make a symlink from the Snap .config directory:
+Also on first startup, a configuration file, **es_settings.cfg** will be generated with all the default settings, and a **es_systems.cfg** file will also be copied from the program resource folder. This file contains the game ROM and emulator settings and can be modified if needed. For information on how to do this, refer to the [INSTALL.md](INSTALL.md#es_systemscfg) document.
+
+**Note:** On Linux it's assumed that RetroArch is using the default configuration directory location, i.e. the cores should be located in ~/.config/retroarch/cores. If you've installed RetroArch via a Snap package, make a symlink from the Snap .config directory:
 
 ```
 ln -s ~/snap/retroarch/current/.config/retroarch ~/.config/
 ```
 
-There's a log file in the home directory as well named **es_log.txt**, please refer to this in case of any errors as it should provide information on what went wrong.
+Similarly, if you've installed RetroArch and its cores from your operating system repository, make a symlink to the default directory as well. For instance, this is how to do it for Linux Mint:
+
+```
+mv ~/.config/retroarch/cores ~/.config/retroarch/cores_OLD
+ln -s /usr/lib/x86_64-linux-gnu/libretro ~/.config/retroarch/cores
+```
+
+As an alternative to this, you can also modify es_systems.cfg which will be located in ~/.emulationstation after you've started the application at least once.
+
+**Note:** There's a log file in the home directory named **es_log.txt**, please refer to this in case of any errors as it should provide information on what went wrong. Starting ES-DE with the --debug flag provides more detailed information and is a good idea to use in case of problems.
 
 After ES-DE finds at least one game file, it will populate that game system and the application will start. If there are no game files, an error messsage will be shown, explaining that you need to install your game files into your ROM directory. You will also be given a choice to change the ROM directory if you don't want to use the default path. Please refer to the game installation procedure below in this document for more information regarding this.
 
 ![alt text](images/v1.0/es-de_v1.0_ui_easy_setup.png "ES-DE Easy Setup")
-_This is the error dialog shown if no game files were found. But it also lets you configure the ROM directory if you don't want to use the default one._
+_This is the error dialog shown if no game files were found. It also lets you configure the ROM directory if you don't want to use the default one. Note that the directory is the real physical path, and that your operating system may present this as a localized path if you are using a language other than English._
 
 
 ## Input device configuration