README: Convert to markdown, add more info

Add screenshots for Windows installation steps and add new sections
about cross-compilation and enabling qt5.

1 files changed, 276 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 00000000..e4efc5e1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,276 @@
+# Description
+
+Cerbero is a cross-platform build aggregator for Open Source projects that builds
+and creates native packages for different platforms, architectures and distributions.
+It supports both native compilation and cross compilation and can run on macOS,
+Linux, and Windows.
+
+Projects are defined using recipe files (.recipe), which provide a description
+of the project being built such as name, version, licenses, sources and the way
+it's built. It also provide listing of files, which is later used for the packaging.
+
+Packages are defined using package files (.package), describing the package name,
+version, license, maintainer and other fields used to create the packages. A
+package wraps a list of recipes, from which the list of files belonging to the
+package will be extracted.
+
+# Minimum Requirements
+
+Cerbero provides bootstrapping facilities for all platforms, but it still needs a
+minimum base to bootstrap on top of.
+
+### Linux Setup
+
+On Linux, you will only need a distribution with python >= 3.5. Cerbero will
+use your package manager to install all other required packages during
+[bootstrap](#Bootstrap).
+
+### macOS Setup
+
+On macOS you will need to have install the following software:
+
+ * XCode
+ * Python 3.5+ https://www.python.org/downloads/
+
+Cerbero will build all other required packages during [bootstrap](#Bootstrap).
+
+### Windows Setup
+
+The initial setup on Windows is somewhat longer since the required packages
+must be installed manually. Detailed steps on what you need to install are
+**[at the bottom of the page](#installing-minimum-requirements-on-windows)**.
+
+# Running Cerbero
+
+Despite the presence of `setup.py` this tool does not need installation. It is invoked via the
+cerbero-uninstalled script, which should be invoked as `./cerbero-uninstalled`, or you can add
+the cerbero directory in your path and invoke it as `cerbero-uninstalled`.
+
+On Windows it should be invoked as "python ./cerbero-uninstalled".
+
+### Bootstrap
+
+Before using cerbero for the first time, you will need to run the bootstrap
+command.  This command installs the missing parts of the build system using the
+packages manager when available, and also downloads the necessary toolchains
+when building for Windows or Android.
+
+Note that this will take a while (a couple hours or even more on Windows).
+
+```sh
+$ ./cerbero-uninstalled bootstrap
+```
+
+### Command Reference
+
+```shell
+# Help
+$ ./cerbero-uninstalled --help
+
+# Command-specific help
+$ ./cerbero-uninstalled <command> --help
+
+# List available recipes
+$ ./cerbero-uninstalled list
+
+# Build a recipe
+$ ./cerbero-uninstalled build glib
+
+# Force-rebuild a single recipe
+$ ./cerbero-uninstalled buildone glib
+
+# Create a package (this automatically builds all recipes in the package)
+$ ./cerbero-uninstalled package gstreamer-1.0
+```
+
+## Cross Compilation
+
+If you're using Cerbero to cross-compile to iOS, Android, or Cross-MinGW, you
+must select the appropriate config file and pass it to all steps: bootstrap,
+build, package, etc.
+
+For example if you're on Linux and you want to build for Android Universal, you
+must run:
+
+```sh
+# Bootstrap for Android Universal on Linux
+$ ./cerbero-uninstalled -c config/cross-android-universal.cbc bootstrap
+
+# Build everything and package for Android Universal
+$ ./cerbero-uninstalled -c config/cross-android-universal.cbc package gstreamer-1.0
+```
+
+Here's a list of config files for each target machine:
+
+#### Linux Targets
+
+Target            | Config file
+:-----------------|:-----------
+MinGW 32-bit      | `cross-win32.cbc`
+MinGW 64-bit      | `cross-win64.cbc`
+Android Universal | `cross-android-universal.cbc`
+Android ARM64     | `cross-android-arm64.cbc`
+Android ARMv7     | `cross-android-armv7.cbc`
+Android x86       | `cross-android-x86.cbc`
+Android x86_64    | `cross-android-x86-64.cbc`
+
+#### macOS Targets
+
+Target                 | Config file
+:----------------------|:-----------
+macOS System Framework | `osx-x86-64.cbc`
+iOS Universal          | `cross-ios-universal.cbc`
+iOS ARM64              | `cross-ios-arm64.cbc`
+iOS ARMv7              | `cross-ios-armv7.cbc`
+iOS x86                | `cross-ios-x86.cbc`
+iOS x86_64              | `cross-ios-x86-64.cbc`
+
+#### Windows Targets
+
+Target                     | Config file
+:--------------------------|:-----------
+MinGW 32-bit System Prefix | `win32.cbc`
+MinGW 64-bit System Prefix | `win64.cbc`
+
+Currently no cross targets are supported on Windows.
+
+# Enabling Qt5 support
+
+Starting with version 1.15.2, Cerbero has built-in support for building the Qt5
+QML GStreamer plugin. You can toggle that on by enabling the `qt5` variant:
+
+* Invoke `cerbero-uninstalled` as `cerbero-uninstalled -v qt5`, or
+
+* Edit `~/.cerbero/cerbero.cbc` and add `variants = ['qt5']` at the bottom.
+  Create the file if it doesn't exist.
+
+You must also tell Cerbero where your Qt5 installation prefix is. You can do it
+in one of two ways:
+
+* Set the `QT5_PREFIX` environment variable pointed to your prefix, f.ex.
+  `/path/to/Qt5.12.0/5.12.0`, or
+
+* Set the `QMAKE` environment variable to point to the `qmake` that you want to
+  use, f.ex. `/path/to/Qt5.12.0/5.12.0/ios/bin/qmake`
+
+**NOTE:** You must use `QT5_PREFIX` for Android Universal because it needs to
+select the correct toolchain prefix for each architecture.
+
+Next, run `package`:
+
+```sh
+$ ./cerbero-uninstalled -v qt5 [-c ...] package gstreamer-1.0
+```
+
+This will try to build the Qt5 QML plugin and error out if Qt5 could not be
+found or if the plugin could not be built. The plugin will be automatically
+added to the package outputted.
+
+**NOTE:** The package outputted will not contain a copy of the Qt5 libraries in
+it. You must link to them while building your app yourself.
+
+# Installing Minimum Requirements on Windows
+
+These steps are necessary for using Cerbero on Windows.
+
+#### Install Python 3.5 or newer (either 32-bit or 64-bit)
+
+Download the [Windows executable installer](https://www.python.org/downloads/) and run it.
+
+* On the first page of the installer, select the following:
+
+![Enable Add Python to PATH, then click Customize Installation](/data/images/py-installer-page1.png)
+
+* On the second page, the defaults are fine
+
+* Third page, you must select the following options:
+
+![Enable Install for all users, associate files with Python, add Python to environment variables, and customize the install location to not have any spaces in it](/data/images/py-installer-page3.png)
+
+#### Install Git for Windows
+
+Download the [Git for Windows installer](https://gitforwindows.org/) and run it.
+
+* First page is the license
+
+* Next page is `Select Components`, the defaults are fine, enable whatever else you prefer
+
+* Next `Choosing the default editor used by Git`, select whatever you prefer
+
+* Next `Adjusting your PATH environment`, you *must* select as shown in the screenshot
+
+![Select "Git from the command line and also from 3rd-party software"](/data/images/git-installer-PATH.png)
+
+* Next `Choosing HTTPS transport backend`, default is fine
+
+* Next `Configuring the line ending conversions`, you *must* select as shown in the screenshot
+
+![Select "Git from the command line and also from 3rd-party software"](/data/images/git-installer-line-endings.png)
+
+* Next `Configuring the terminal emulator`, default is fine
+
+* Next `Configuring extra options`, defaults are fine
+
+Git will be installed at `C:\Program Files\Git`.
+
+#### Install MSYS/MinGW
+
+Download the [`mingw-get-setup` executable installer](http://sourceforge.net/projects/mingw/files/Installer/mingw-get-setup.exe/download) and run it.
+
+* First page, keep all the options as-is
+
+* Second page will download the latest package catalogue and base packages
+
+* Once done, the MinGW Installation Manager will open, select the following
+  packages under Basic Setup:
+
+![Under Basic Setup, select mingw-developer-toolkit, mingw32-base, and msys-base](/data/images/msys-install-packages.png)
+
+Then, click on the `Installation` menu and select `Apply Changes`. MSYS will be
+installed at `C:\MinGW`.
+
+**IMPORTANT:** After installation, you must create a shortcut on the desktop to
+`C:\MinGW\msys\1.0\msys.bat` which will run the MinGW shell. **You must run
+Cerbero from inside that**.
+
+**NOTE**: Cerbero does not use the MinGW compiler toolchain shipped with MSYS.
+We download our own custom GCC toolchain during [bootstrap](#Bootstrap).
+
+**NOTE**: MSYS is not the same as [MSYS2](https://www.msys2.org/), and the
+GStreamer project does not support running Cerbero inside the MSYS2
+environment. Things may work or they may break, and you get to keep the pieces.
+
+#### Install Visual Studio 2015 or newer
+
+This is needed for correctly generating import libraries for recipes built with
+MinGW. Both the Community build and the Professional build are supported.
+
+You can find all versions of Visual Studio at:
+https://visualstudio.microsoft.com/vs/older-downloads/
+
+#### Install other tools
+
+* CMake: http://www.cmake.org/cmake/resources/software.html
+
+* WiX 3.11.1 installer: https://github.com/wixtoolset/wix3/releases/tag/wix3111rtm
+
+#### Important Windows-specific Notes
+
+You should add the cerbero git directory to the list of excluded folders in your
+anti-virus, or you will get random build failures when Autotools does file
+operations such as renames and deletions. It will also slow your build by
+about 3-4x.
+
+Cerbero must be run in the MingGW shell, which is accessible from the main menu
+or desktop. If it is not, create a shortcut on the desktop to `C:\MinGW\msys\1.0\msys.bat`
+
+The path to your `$HOME` must not contain spaces. If your Windows username
+contains spaces, you can create a new directory in `/home` and execute:
+
+```cmd
+$ echo 'export HOME=/home/newdir' > ~/.profile
+```
+
+Then restart your shell and type `cd` to go to the new home directory.
+
+Note that inside the shell, `/` is mapped to `C:\Mingw\msys\1.0\`