Xargon/ES-DE
1
0
Fork 0
mirror of https://github.com/RetroDECK/ES-DE.git synced 2024-11-21 21:55:38 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Documentation update.

Browse source
This commit is contained in:
Leon Styhre 2021-05-14 11:01:55 +02:00
parent 98859c89c9
commit 57a5e1ccb3
7 changed files with 238 additions and 41 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
CHANGELOG.md
View file

@ -10,6 +10,9 @@
### Detailed list of changes ### Detailed list of changes
* Added a new video player based on FFmpeg
* Changed the language standard from C++11 to C++14
### Bug fixes ### Bug fixes
## Version 1.0.1 ## Version 1.0.1

13
CREDITS.md
View file

@ -27,10 +27,13 @@ Please find the individual license files inside the `licenses` directory. There
# Libraries # Libraries
cURL \ cURL \
http://curl.haxx.se https://curl.haxx.se
FFmpeg \
https://ffmpeg.org
FreeType \ FreeType \
http://www.freetype.org https://www.freetype.org
FreeImage \ FreeImage \
http://www.freeimage.sourceforge.net http://www.freeimage.sourceforge.net
@ -45,13 +48,13 @@ nanosvg \
https://github.com/memononen/nanosvg https://github.com/memononen/nanosvg
pugixml \ pugixml \
http://pugixml.org https://pugixml.org
RapdidJSON \ RapdidJSON \
http://rapidjson.org https://rapidjson.org
SDL2 \ SDL2 \
http://www.libsdl.org https://www.libsdl.org
# Resources # Resources

118
INSTALL-DEV.md
View file

@ -19,7 +19,7 @@ Any code editor can be used of course, but I recommend [VSCode](https://code.vis
## Building on Unix ## Building on Unix
The code has some dependencies. For building, you'll need CMake and development packages for cURL, FreeImage, FreeType, libVLC, pugixml, SDL2 and RapidJSON. The code has some dependencies. For building, you'll need CMake and development packages for cURL, FFmpeg, FreeImage, FreeType, libVLC, pugixml, SDL2 and RapidJSON.
**Installing dependencies:** **Installing dependencies:**
@ -27,7 +27,7 @@ The code has some dependencies. For building, you'll need CMake and development
All of the required packages can be installed with apt-get: All of the required packages can be installed with apt-get:
``` ```
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 sudo apt-get install build-essential git cmake libsdl2-dev libavcodec-dev libavformat-dev libavutil-dev libswresample-dev libswscale-dev libfreeimage-dev libfreetype6-dev libcurl4-openssl-dev libpugixml-dev rapidjson-dev libasound2-dev vlc libvlc-dev libgl1-mesa-dev
``` ```
**On Fedora** **On Fedora**
@ -40,7 +40,7 @@ sudo dnf install ./rpmfusion-free-release-33.noarch.rpm
Then use dnf to install all the required packages: 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 sudo dnf install gcc-c++ cmake SDL2-devel ffmpeg-devel freeimage-devel freetype-devel curl-devel pugixml-devel rapidjson-devel alsa-lib-devel mesa-libGL-devel vlc vlc-devel
``` ```
**On Manjaro** **On Manjaro**
@ -48,14 +48,14 @@ sudo dnf install gcc-c++ cmake SDL2-devel freeimage-devel freetype-devel curl-de
Use pacman to install all the required packages: Use pacman to install all the required packages:
``` ```
pacman -S gcc make cmake pkgconf sdl2 freeimage freetype2 pugixml rapidjson vlc sudo pacman -S gcc make cmake pkgconf sdl2 ffmpeg freeimage freetype2 pugixml rapidjson vlc
``` ```
**On FreeBSD** **On FreeBSD**
Use pkg to install the dependencies: Use pkg to install the dependencies:
``` ```
pkg install git pkgconf cmake sdl2 freeimage pugixml rapidjson vlc pkg install git pkgconf cmake sdl2 ffmpeg freeimage pugixml rapidjson vlc
``` ```
Clang/LLVM and cURL should already be installed in the base OS image. Clang/LLVM and cURL should already be installed in the base OS image.
@ -64,7 +64,7 @@ Clang/LLVM and cURL should already be installed in the base OS image.
Use pkgin to install the dependencies: Use pkgin to install the dependencies:
``` ```
pkgin install git cmake pkgconf SDL2 freeimage pugixml rapidjson vlc pkgin install git cmake pkgconf SDL2 ffmpeg4 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. 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.
@ -73,7 +73,7 @@ NetBSD ships with GCC by default, and although you should be able to install and
Use pkg_add to install the dependencies: Use pkg_add to install the dependencies:
``` ```
pkg_add cmake pkgconf sdl2 freeimage vlc pkg_add cmake pkgconf sdl2 ffmpeg freeimage vlc
``` ```
In the same manner as for FreeBSD, Clang/LLVM and cURL should already be installed by default. In the same manner as for FreeBSD, Clang/LLVM and cURL should already be installed by default.
@ -307,19 +307,19 @@ CPack: - Run preinstall target for: emulationstation-de
CPack: - Install project: emulationstation-de [] CPack: - Install project: emulationstation-de []
CPack: Create package CPack: Create package
CPackDeb: - Generating dependency list CPackDeb: - Generating dependency list
CPack: - package: /home/myusername/emulationstation-de/emulationstation-de-1.0.0-x64.deb generated. CPack: - package: /home/myusername/emulationstation-de/emulationstation-de-1.1.0-x64.deb generated.
``` ```
You may like to check that the dependencies look fine, as they're automatically generated by CMake: You may like to check that the dependencies look fine, as they're automatically generated by CMake:
``` ```
dpkg -I ./emulationstation-de-1.0.0-x64.deb dpkg -I ./emulationstation-de-1.1.0-x64.deb
``` ```
The package can now be installed using a package manager, for example apt: The package can now be installed using a package manager, for example apt:
``` ```
sudo apt install ./emulationstation-de-1.0.0-x64.deb sudo apt install ./emulationstation-de-1.1.0-x64.deb
``` ```
To build an RPM package instead, set the flag LINUX_CPACK_GENERATOR to RPM when running cmake, for example: To build an RPM package instead, set the flag LINUX_CPACK_GENERATOR to RPM when running cmake, for example:
@ -338,7 +338,7 @@ CPack: - Run preinstall target for: emulationstation-de
CPack: - Install project: emulationstation-de [] CPack: - Install project: emulationstation-de []
CPack: Create package CPack: Create package
CPackRPM: Will use GENERATED spec file: /home/myusername/emulationstation-de/_CPack_Packages/Linux/RPM/SPECS/emulationstation-de.spec CPackRPM: Will use GENERATED spec file: /home/myusername/emulationstation-de/_CPack_Packages/Linux/RPM/SPECS/emulationstation-de.spec
CPack: - package: /home/myusername/emulationstation-de/emulationstation-de-1.0.0-x64.rpm generated. CPack: - package: /home/myusername/emulationstation-de/emulationstation-de-1.1.0-x64.rpm generated.
``` ```
On Fedora, you need to install rpmbuild before this command can be run though: On Fedora, you need to install rpmbuild before this command can be run though:
@ -348,17 +348,17 @@ sudo dnf install rpm-build
After the package generation you can check that the metadata looks fine using this command: After the package generation you can check that the metadata looks fine using this command:
``` ```
rpm -qi ./emulationstation-de-1.0.0-x64.rpm rpm -qi ./emulationstation-de-1.1.0-x64.rpm
``` ```
And to see the automatically generated dependency requirements, run this: And to see the automatically generated dependency requirements, run this:
``` ```
rpm -q --requires ./emulationstation-de-1.0.0-x64.rpm rpm -q --requires ./emulationstation-de-1.1.0-x64.rpm
``` ```
And of course, you can also install the package: And of course, you can also install the package:
``` ```
sudo dnf install ./emulationstation-de-1.0.0-x64.rpm sudo dnf install ./emulationstation-de-1.1.0-x64.rpm
``` ```
## Building on macOS ## Building on macOS
@ -382,7 +382,7 @@ Be aware that Homebrew can be really slow, especially when it compiles packages
Install the required tools and dependencies: Install the required tools and dependencies:
``` ```
brew install cmake pkg-config sdl2 freeimage freetype pugixml rapidjson brew install cmake pkg-config nasm fdk-aac libvpx sdl2 freeimage freetype pugixml rapidjson
``` ```
Curl could optionally be installed too, but normally the version shipped with macOS is fine to use. Curl could optionally be installed too, but normally the version shipped with macOS is fine to use.
@ -392,6 +392,18 @@ Install VLC/libVLC as well:
brew install --cask vlc brew install --cask vlc
``` ```
**Compiling FFmpeg:**
The FFmpeg build distributed via Homebrew has a lot of dependencies we don't need, and which would make it very difficult to package it in an installer. Instead we will build this software with only some limited options:
```
git clone https://github.com/FFmpeg/FFmpeg.git
cd FFmpeg
git checkout n4.4
./configure --prefix=/usr/local --enable-gpl --enable-nonfree --enable-shared --enable-libfdk-aac --enable-libvpx
sudo make install
```
**Some additional/optional steps:** **Some additional/optional steps:**
Enable developer mode to avoid annoying password requests when attaching the debugger to a process: Enable developer mode to avoid annoying password requests when attaching the debugger to a process:
@ -455,15 +467,13 @@ Be aware that the approach taken for macOS has the limitation that you can't bui
Due to the Apple notarization requirement implemented as of macOS 10.14.5 a build with simple code signing is needed for versions up to 10.13 and another build with both code signing and notarization will be required for versions 10.14 and higher. Due to the Apple notarization requirement implemented as of macOS 10.14.5 a build with simple code signing is needed for versions up to 10.13 and another build with both code signing and notarization will be required for versions 10.14 and higher.
macOS code signing is beyond the scope of this document but a short summary is that signing works as intended and can be enabled by uncommenting the following lines in the es-app/CMakeLists.txt file: macOS code signing is beyond the scope of this document, but the option MACOS_CODESIGN_IDENTITY is used to to specify the code signing certificate identity, for example:
``` ```
# Uncomment the following lines and change to your certificate identity to enable code signing. cmake -DMACOS_CODESIGN_IDENTITY="My Name" .
#set(CPACK_BUNDLE_APPLE_CERT_APP "Developer ID Application: <identity>")
#if(${CMAKE_OSX_DEPLOYMENT_TARGET} VERSION_GREATER 10.13)
# set(CPACK_BUNDLE_APPLE_CODESIGN_PARAMETER "--deep --force --options runtime")
#endif()
``` ```
Assuming the code signing ceritificate is properly setup in Keychain Access, the process will be automatic and the resulting DMG package can be notarized as-is.
**Legacy build:** **Legacy build:**
Normally ES-DE is meant to be built for macOS 10.14 and higher, but a legacy build for earlier operating system versions can be enabled. This has been tested with a minimum version of 10.11 and it's unclear if it works with even older macOS versions. Normally ES-DE is meant to be built for macOS 10.14 and higher, but a legacy build for earlier operating system versions can be enabled. This has been tested with a minimum version of 10.11 and it's unclear if it works with even older macOS versions.
@ -477,6 +487,12 @@ You also need to modify es-app/assets/EmulationStation-DE_Info.plist and set the
As macOS does not have any package manager which would have handled the library dependencies, we need to bundle the required shared libraries with the application. Copy the following .dylib files from their respective installation directories to the emulationstation-de build directory: As macOS does not have any package manager which would have handled the library dependencies, we need to bundle the required shared libraries with the application. Copy the following .dylib files from their respective installation directories to the emulationstation-de build directory:
``` ```
libavcodec.58.dylib
libavformat.58.dylib
libavutil.56.dylib
libswresample.3.dylib
libswscale.5.dylib
libfdk-aac.2.dylib
libSDL2-2.0.0.dylib libSDL2-2.0.0.dylib
libfreeimage.dylib libfreeimage.dylib
libfreetype.6.dylib libfreetype.6.dylib
@ -485,19 +501,26 @@ libvlc.dylib
libvlccore.dylib libvlccore.dylib
``` ```
The first four would normally be installed by Homebrew under /usr/local/lib and the VLC libraries should be installed under /Applications/VLC.app/Contents/MacOS/lib/ All except the VLC libraries should be located in /usr/local/lib. The VLC libraries should be located in /Applications/VLC.app/Contents/MacOS/lib/
Note that the filenames could be slightly different depending on what versions you have installed on your system. Note that the filenames could be slightly different depending on what versions you have installed on your system.
For libfreetype there is a dependency on libpng and you need to rewrite the rpath to point to the local directory, otherwise any generated installation package will not work on other computers. Make sure that you have write permissions to libfreetype.6.dylib before attempting to run this: There are some secondary internal dependencies between some of these library files, and these are baked into the files as absolut paths. As such we need to rewrite these to rpaths (relative paths) which is done using the install_name_tool command.
A script is available to automate this, `tools/macOS_change_dylib_rpaths.sh`
Simply run this script:
``` ```
cd emulationstation-de cd emulationstation-de
install_name_tool -change /usr/local/opt/libpng/lib/libpng16.16.dylib @rpath/libpng16.16.dylib libfreetype.6.dylib tools/macOS_change_dylib_rpaths.sh
install_name_tool -add_rpath @executable_path libfreetype.6.dylib Found file libfreetype.6.dylib - changing rpaths
Found file libavcodec.58.dylib - changing rpaths
Found file libavformat.58.dylib - changing rpaths
Found file libswresample.3.dylib - changing rpaths
Found file libswscale.5.dylib - changing rpaths
``` ```
Verify that it worked as expected by running `otool -L libfreetype.6.dylib` - you should see something like the following: Verify that it worked as expected by running the otool command, for example `otool -L libfreetype.6.dylib` should show something like the following:
``` ```
libfreetype.6.dylib: libfreetype.6.dylib:
@ -508,7 +531,9 @@ libfreetype.6.dylib:
/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1226.10.1) /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1226.10.1)
``` ```
You of course only need to run this once, well at least until you replace the library in case of moving to a newer version or so. It's unclear why the first line shows a reference to itself, and this line apparently can't be modified using the install_name_tool command. It doesn't matter though and the application will work fine even if this path does not exist on the system.
You of course only need to change the paths to rpaths once, well at least until you replace the libraries in case of moving to a newer version or so.
In addition to these libraries, you need to create a `plugins` directory and copy over the following VLC libraries, which are normally located in `/Applications/VLC.app/Contents/MacOS/plugins/`: In addition to these libraries, you need to create a `plugins` directory and copy over the following VLC libraries, which are normally located in `/Applications/VLC.app/Contents/MacOS/plugins/`:
@ -549,9 +574,15 @@ This will be the directory structure for the installation:
/Applications/EmulationStation Desktop Edition.app/Contents/Info.plist /Applications/EmulationStation Desktop Edition.app/Contents/Info.plist
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/EmulationStation /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/EmulationStation
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libSDL2-2.0.0.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libSDL2-2.0.0.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavcodec.58.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavformat.58.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libavutil.56.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libfdk-aac.2.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libfreeimage.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libfreeimage.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libfreetype.6.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libfreetype.6.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libpng16.16.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libpng16.16.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libswresample.3.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libswscale.5.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvlc.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvlc.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvlccore.dylib /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/libvlccore.dylib
/Applications/EmulationStation Desktop Edition.app/Contents/MacOS/plugins/* /Applications/EmulationStation Desktop Edition.app/Contents/MacOS/plugins/*
@ -591,7 +622,7 @@ CPack: Install projects
CPack: - Run preinstall target for: emulationstation-de CPack: - Run preinstall target for: emulationstation-de
CPack: - Install project: emulationstation-de [] CPack: - Install project: emulationstation-de []
CPack: Create package CPack: Create package
CPack: - package: /Users/myusername/emulationstation-de/EmulationStation-DE-1.0.0-x64.dmg generated. CPack: - package: /Users/myusername/emulationstation-de/EmulationStation-DE-1.1.0-x64.dmg generated.
``` ```
Generating .dmg installers on older version of macOS seems to make them forward compatible to a pretty good extent, for instance building on El Capitan seems to generate an application that is usable on Catalina and Big Sur. The other way around does however not seem to be true, which is quite unsurprising. Generating .dmg installers on older version of macOS seems to make them forward compatible to a pretty good extent, for instance building on El Capitan seems to generate an application that is usable on Catalina and Big Sur. The other way around does however not seem to be true, which is quite unsurprising.
@ -639,7 +670,7 @@ add_custom_command(TARGET EmulationStation POST_BUILD COMMAND ${CMAKE_INSTALL_NA
Both MSVC and MinGW (GCC) work fine for building ES-DE on Windows. Both MSVC and MinGW (GCC) work fine for building ES-DE on Windows.
As much as I would like to exclude support for MSVC, this proprietary compiler simply works much better when developing as it's much faster than MinGW when linking debug builds and when actually debugging. For release builds though MinGW is very fast and it seems as if ES-DE starts around 18% faster when built with MinGW so this compiler probably generates more efficient code overall. As well MSVC requires a lot more junk DLL files to be distributed with the application so it's not a good candidate for the final release build. Although I would prefer to exclude support for MSVC, this proprietary compiler simply works much better when developing as it's much faster than MinGW when linking debug builds and when actually debugging. For release builds though MinGW is very fast and it seems as if ES-DE starts around 18% faster when built with MinGW so this compiler probably generates more efficient code overall. As well MSVC requires a lot more junk DLL files to be distributed with the application so it's not a good candidate for the final release build.
For this reason I think MSVC makes sense for development and MinGW for the releases. For this reason I think MSVC makes sense for development and MinGW for the releases.
@ -695,6 +726,9 @@ In the description below it's assumed that all build steps for MinGW/GCC will be
**Download the dependency packages:** **Download the dependency packages:**
FFmpeg (choose a package with win64-gpl-shared in the filename, the latest snapshot build should generally be fine to use) \
[https://github.com/BtbN/FFmpeg-Builds/releases](https://github.com/BtbN/FFmpeg-Builds/releases)
FreeImage (binary distribution) \ FreeImage (binary distribution) \
[https://sourceforge.net/projects/freeimage](https://sourceforge.net/projects/freeimage) [https://sourceforge.net/projects/freeimage](https://sourceforge.net/projects/freeimage)
@ -803,10 +837,12 @@ As there is no standardized include directory structure in Windows, you need to
Make a directory in your build environment tree, for instance under `C:\Programming\include` Make a directory in your build environment tree, for instance under `C:\Programming\include`
Copy the include files from cURL, FreeImage, FreeType, GLEW, pugixml, RapidJSON, SDL2 and VLC to this directory. Copy the include files for cURL, FFmpeg, FreeImage, FreeType, GLEW, pugixml, RapidJSON, SDL2 and VLC to this directory.
You may need to create the SDL2 directory manually and copy the header files there. You may need to create the SDL2 directory manually and copy the header files there.
For FFmpeg, copy the directories libavcodec, libavformat, libavutil, libswresample and libswscale.
It should then look something like this: It should then look something like this:
``` ```
@ -816,6 +852,11 @@ FreeImage.h
freetype/ freetype/
ft2build.h ft2build.h
GL/ GL/
libavcodec/
libavformat/
libavutil/
libswresample/
libswscale/
pugiconfig.hpp pugiconfig.hpp
pugixml.hpp pugixml.hpp
rapidjson/ rapidjson/
@ -831,6 +872,16 @@ Copy the files to the `emulationstation-de` build directory. Most of them will c
**Required files for MSVC:** **Required files for MSVC:**
``` ```
avcodec-59.dll
avcodec.lib
avformat-59.dll
avformat.lib
avutil-57.dll
avutil.lib
swresample-4.dll
swresample.lib
swscale-6.dll
swscale.lib
FreeImage.dll FreeImage.dll
FreeImage.lib FreeImage.lib
freetype.dll freetype.dll
@ -876,6 +927,11 @@ lib /def:libvlc.def /out:libvlc.lib /machine:x64
**Required files for MinGW:** **Required files for MinGW:**
``` ```
avcodec-59.dll
avformat-59.dll
avutil-57.dll
swresample-4.dll
swscale-6.dll
FreeImage.dll FreeImage.dll
glew32.dll glew32.dll
libcrypto-1_1-x64.dll (from the OpenSSL package, located in Git MinGW/MSYS2 under \mingw64\bin) libcrypto-1_1-x64.dll (from the OpenSSL package, located in Git MinGW/MSYS2 under \mingw64\bin)
@ -993,7 +1049,7 @@ CPack: Install projects
CPack: - Run preinstall target for: emulationstation-de CPack: - Run preinstall target for: emulationstation-de
CPack: - Install project: emulationstation-de [] CPack: - Install project: emulationstation-de []
CPack: Create package CPack: Create package
CPack: - package: C:/Programming/emulationstation-de/EmulationStation-DE-1.0.0-x64.exe generated. CPack: - package: C:/Programming/emulationstation-de/EmulationStation-DE-1.1.0-x64.exe generated.
``` ```
The default installation directory suggested by the installer is `C:\Program Files\EmulationStation-DE` but this can of course be changed by the user. The default installation directory suggested by the installer is `C:\Program Files\EmulationStation-DE` but this can of course be changed by the user.

2
README.md
View file

@ -20,7 +20,7 @@ The current version 1.0 has been tested on the following operating systems (all
* Fedora 33 Workstation * Fedora 33 Workstation
* FreeBSD 12.2 * FreeBSD 12.2
* NetBSD 9.1 * NetBSD 9.1
* OpenBSD 6.8 (limited testing only) * OpenBSD 6.8
* macOS 11 "Big Sur" * macOS 11 "Big Sur"
* macOS 10.15 "Catalina" (limited testing only) * macOS 10.15 "Catalina" (limited testing only)
* macOS 10.14 "Mojave" (limited testing only) * macOS 10.14 "Mojave" (limited testing only)

11
USERGUIDE-DEV.md
View file

@ -41,9 +41,10 @@ The following operating systems have been tested (all for the x86 architecture):
* Fedora 33 Workstation * Fedora 33 Workstation
* FreeBSD 12.2 * FreeBSD 12.2
* NetBSD 9.1 * NetBSD 9.1
* OpenBSD 6.8 (limited testing only) * OpenBSD 6.8
* macOS 11 "Big Sur" * macOS 11 "Big Sur"
* macOS 10.15 "Catalina" (limited testing only) * macOS 10.15 "Catalina" (limited testing only)
* macOS 10.14 "Mojave" (limited testing only)
* macOS 10.11 "El Capitan" * macOS 10.11 "El Capitan"
* Windows 10 * Windows 10
* Windows 8.1 * Windows 8.1
@ -1046,6 +1047,10 @@ This option sets the display to use for ES-DE for multi-monitor setups. The poss
This gives you a choice between _Normal_ and _Borderless_ modes. With the borderless being more seamless as the ES-DE window will always stay on top of other windows so the taskbar will not be visible when launching and returning from games. It will however break the alt-tab application switching of your window manager. For normal fullscreen mode, if a lower resolution than the screen resolution has been set via the --resolution command line argument, ES-DE will render in full screen at the lower resolution. If a higher resolution than the screen resolution has been set, ES-DE will run in a window. For the borderless mode, any changes to the resolution will make ES-DE run in a window. This gives you a choice between _Normal_ and _Borderless_ modes. With the borderless being more seamless as the ES-DE window will always stay on top of other windows so the taskbar will not be visible when launching and returning from games. It will however break the alt-tab application switching of your window manager. For normal fullscreen mode, if a lower resolution than the screen resolution has been set via the --resolution command line argument, ES-DE will render in full screen at the lower resolution. If a higher resolution than the screen resolution has been set, ES-DE will run in a window. For the borderless mode, any changes to the resolution will make ES-DE run in a window.
**Video player**
This gives the choice between VLC or FFmpeg, which is applied to both the gamelist videos and the video screensaver.
**When to save game metadata** **When to save game metadata**
The metadata for a game is updated by scraping and by manual editing (using the metadata editor), but also when launching it as this updates the _Times played_ counter and the _Last played_ date. This setting enables you to define when to write such metadata changes to the gamelist.xml files. Setting the option to _Never_ will disable writing to these files altogether, except for some special conditions such as when a game is manually deleted using the metadata editor, or when scraping using the multi-scraper (the multi-scraper will always save any updates immediately to the gamelist.xml files). In theory _On exit_ will give some performance gains, but it's normally recommended to leave the setting at its default value which is _Always_. Note that with the settings set to _Never_, any updates such as the _Last played_ date will still be shown on screen, but during the next application startup, any values previously saved to the gamelist.xml files will be read in again. As well, when changing this setting to _Always_ from either of the two other options, any pending changes will be immediately written to the gamelist.xml files. The metadata for a game is updated by scraping and by manual editing (using the metadata editor), but also when launching it as this updates the _Times played_ counter and the _Last played_ date. This setting enables you to define when to write such metadata changes to the gamelist.xml files. Setting the option to _Never_ will disable writing to these files altogether, except for some special conditions such as when a game is manually deleted using the metadata editor, or when scraping using the multi-scraper (the multi-scraper will always save any updates immediately to the gamelist.xml files). In theory _On exit_ will give some performance gains, but it's normally recommended to leave the setting at its default value which is _Always_. Note that with the settings set to _Never_, any updates such as the _Last played_ date will still be shown on screen, but during the next application startup, any values previously saved to the gamelist.xml files will be read in again. As well, when changing this setting to _Always_ from either of the two other options, any pending changes will be immediately written to the gamelist.xml files.
@ -1486,7 +1491,7 @@ Consider the table below a work in progress as it's obvioulsy not fully populate
| Game system name | Full name | Default emulator | Recommended game setup | | Game system name | Full name | Default emulator | Recommended game setup |
| :-------------------- | :--------------------------------------------- | :-------------------------------- | :----------------------------------- | | :-------------------- | :--------------------------------------------- | :-------------------------------- | :----------------------------------- |
| 3do | 3DO | | | | 3do | 3DO | | |
| 64dd | Nintendo 64DD | RetroArch (Mupen64Plus-Next) [no n64 emulator available on macOS?] | | | 64dd | Nintendo 64DD | RetroArch (Mupen64Plus-Next on Unix and Windows, ParaLLEl N64 on macOS) | |
| ags | Adventure Game Studio game engine | | | | ags | Adventure Game Studio game engine | | |
| amiga | Commodore Amiga | RetroArch (P-UAE)* | WHDLoad hard disk image in .hdf or .hdz format in root folder, or diskette image in .adf format in root folder if single-disk, or in separate folder with .m3u playlist if multi-disk | | amiga | Commodore Amiga | RetroArch (P-UAE)* | WHDLoad hard disk image in .hdf or .hdz format in root folder, or diskette image in .adf format in root folder if single-disk, or in separate folder with .m3u playlist if multi-disk |
| amiga600 | Commodore Amiga 600 | RetroArch (P-UAE)* | WHDLoad hard disk image in .hdf or .hdz format in root folder, or diskette image in .adf format in root folder if single-disk, or in separate folder with .m3u playlist if multi-disk | | amiga600 | Commodore Amiga 600 | RetroArch (P-UAE)* | WHDLoad hard disk image in .hdf or .hdz format in root folder, or diskette image in .adf format in root folder if single-disk, or in separate folder with .m3u playlist if multi-disk |
@ -1556,7 +1561,7 @@ Consider the table below a work in progress as it's obvioulsy not fully populate
| naomi | Sega NAOMI | RetroArch (Flycast) | | | naomi | Sega NAOMI | RetroArch (Flycast) | |
| naomigd | Sega NAOMI GD-ROM | RetroArch (Flycast) | | | naomigd | Sega NAOMI GD-ROM | RetroArch (Flycast) | |
| n3ds | Nintendo 3DS | RetroArch (Citra) | | | n3ds | Nintendo 3DS | RetroArch (Citra) | |
| n64 | Nintendo 64 | RetroArch (Mupen64Plus-Next) [no n64 emulator available on macOS?] | Single archive or ROM file in root folder | | n64 | Nintendo 64 | RetroArch (Mupen64Plus-Next on Unix and Windows, ParaLLEl N64 on macOS) | Single archive or ROM file in root folder |
| nds | Nintendo DS | | | | nds | Nintendo DS | | |
| neogeo | SNK Neo Geo | RetroArch (FinalBurn Neo)* | Single archive file following MAME name standard in root folder | | neogeo | SNK Neo Geo | RetroArch (FinalBurn Neo)* | Single archive file following MAME name standard in root folder |
| neogeocd | SNK Neo Geo CD | RetroArch (NeoCD)* | Single archive in root folder (which includes the CD image and ripped audio) | | neogeocd | SNK Neo Geo CD | RetroArch (NeoCD)* | Single archive in root folder (which includes the CD image and ripped audio) |

3
USERGUIDE.md
View file

@ -41,9 +41,10 @@ The following operating systems have been tested (all for the x86 architecture):
* Fedora 33 Workstation * Fedora 33 Workstation
* FreeBSD 12.2 * FreeBSD 12.2
* NetBSD 9.1 * NetBSD 9.1
* OpenBSD 6.8 (limited testing only) * OpenBSD 6.8
* macOS 11 "Big Sur" * macOS 11 "Big Sur"
* macOS 10.15 "Catalina" (limited testing only) * macOS 10.15 "Catalina" (limited testing only)
* macOS 10.14 "Mojave" (limited testing only)
* macOS 10.11 "El Capitan" * macOS 10.11 "El Capitan"
* Windows 10 * Windows 10
* Windows 8.1 * Windows 8.1

129
licenses/FFmpeg Normal file
View file

@ -0,0 +1,129 @@
# License
Most files in FFmpeg are under the GNU Lesser General Public License version 2.1
or later (LGPL v2.1+). Read the file `COPYING.LGPLv2.1` for details. Some other
files have MIT/X11/BSD-style licenses. In combination the LGPL v2.1+ applies to
FFmpeg.
Some optional parts of FFmpeg are licensed under the GNU General Public License
version 2 or later (GPL v2+). See the file `COPYING.GPLv2` for details. None of
these parts are used by default, you have to explicitly pass `--enable-gpl` to
configure to activate them. In this case, FFmpeg's license changes to GPL v2+.
Specifically, the GPL parts of FFmpeg are:
- libpostproc
- optional x86 optimization in the files
- `libavcodec/x86/flac_dsp_gpl.asm`
- `libavcodec/x86/idct_mmx.c`
- `libavfilter/x86/vf_removegrain.asm`
- the following building and testing tools
- `compat/solaris/make_sunver.pl`
- `doc/t2h.pm`
- `doc/texi2pod.pl`
- `libswresample/tests/swresample.c`
- `tests/checkasm/*`
- `tests/tiny_ssim.c`
- the following filters in libavfilter:
- `signature_lookup.c`
- `vf_blackframe.c`
- `vf_boxblur.c`
- `vf_colormatrix.c`
- `vf_cover_rect.c`
- `vf_cropdetect.c`
- `vf_delogo.c`
- `vf_eq.c`
- `vf_find_rect.c`
- `vf_fspp.c`
- `vf_histeq.c`
- `vf_hqdn3d.c`
- `vf_kerndeint.c`
- `vf_lensfun.c` (GPL version 3 or later)
- `vf_mcdeint.c`
- `vf_mpdecimate.c`
- `vf_nnedi.c`
- `vf_owdenoise.c`
- `vf_perspective.c`
- `vf_phase.c`
- `vf_pp.c`
- `vf_pp7.c`
- `vf_pullup.c`
- `vf_repeatfields.c`
- `vf_sab.c`
- `vf_signature.c`
- `vf_smartblur.c`
- `vf_spp.c`
- `vf_stereo3d.c`
- `vf_super2xsai.c`
- `vf_tinterlace.c`
- `vf_uspp.c`
- `vf_vaguedenoiser.c`
- `vsrc_mptestsrc.c`
Should you, for whatever reason, prefer to use version 3 of the (L)GPL, then
the configure parameter `--enable-version3` will activate this licensing option
for you. Read the file `COPYING.LGPLv3` or, if you have enabled GPL parts,
`COPYING.GPLv3` to learn the exact legal terms that apply in this case.
There are a handful of files under other licensing terms, namely:
* The files `libavcodec/jfdctfst.c`, `libavcodec/jfdctint_template.c` and
`libavcodec/jrevdct.c` are taken from libjpeg, see the top of the files for
licensing details. Specifically note that you must credit the IJG in the
documentation accompanying your program if you only distribute executables.
You must also indicate any changes including additions and deletions to
those three files in the documentation.
* `tests/reference.pnm` is under the expat license.
## External libraries
FFmpeg can be combined with a number of external libraries, which sometimes
affect the licensing of binaries resulting from the combination.
### Compatible libraries
The following libraries are under GPL version 2:
- avisynth
- frei0r
- libcdio
- libdavs2
- librubberband
- libvidstab
- libx264
- libx265
- libxavs
- libxavs2
- libxvid
When combining them with FFmpeg, FFmpeg needs to be licensed as GPL as well by
passing `--enable-gpl` to configure.
The following libraries are under LGPL version 3:
- gmp
- libaribb24
- liblensfun
When combining them with FFmpeg, use the configure option `--enable-version3` to
upgrade FFmpeg to the LGPL v3.
The VMAF, mbedTLS, RK MPI, OpenCORE and VisualOn libraries are under the Apache License
2.0. That license is incompatible with the LGPL v2.1 and the GPL v2, but not with
version 3 of those licenses. So to combine these libraries with FFmpeg, the
license version needs to be upgraded by passing `--enable-version3` to configure.
The smbclient library is under the GPL v3, to combine it with FFmpeg,
the options `--enable-gpl` and `--enable-version3` have to be passed to
configure to upgrade FFmpeg to the GPL v3.
### Incompatible libraries
There are certain libraries you can combine with FFmpeg whose licenses are not
compatible with the GPL and/or the LGPL. If you wish to enable these
libraries, even in circumstances that their license may be incompatible, pass
`--enable-nonfree` to configure. This will cause the resulting binary to be
unredistributable.
The Fraunhofer FDK AAC and OpenSSL libraries are under licenses which are
incompatible with the GPLv2 and v3. To the best of our knowledge, they are
compatible with the LGPL.