1 files changed, 157 insertions, 22 deletions

diff --git a/README.md b/README.md
index 6fa3713..b59d37f 100644
--- a/README.md
+++ b/README.md
@@ -16,47 +16,180 @@ Some key features are:
 - **Formats:** Supports binary, XML, JSON, and OpenStep format
 - **Utility:** Provides a `plistutil` utility for the command-line
 - **Python:** Provides Cython based bindings for Python
-- **Tested:** Uses fuzzing and data compliance tests
+- **Tested:** Uses fuzzing ([OSS-Fuzz](https://github.com/google/oss-fuzz)) and data compliance tests
 - **Efficient:** Lean library with performance and resources in mind
 
-## Installation / Getting started
+## Building
 
-### Debian / Ubuntu Linux
+You need to have a working compiler and development environent available.
 
-First install all required dependencies and build tools:
-```shell
-sudo apt-get install \
+### Prerequisites
+
+* #### Debian/Ubuntu based Linux
+
+  Install all required dependencies and build tools:
+  ```shell
+  sudo apt-get install \
         build-essential \
         checkinstall \
         git \
         autoconf \
         automake \
         libtool-bin
-```
+  ```
+
+  If you want to optionally build the documentation or Python bindings use:
+  ```shell
+  sudo apt-get install \
+        doxygen \
+        cython3
+  ```
+
+* #### macOS
+
+  Make sure the Xcode command line tools are installed. Then, use either [MacPorts](https://www.macports.org/)
+  or [Homebrew](https://brew.sh/) to install `automake`, `autoconf`, and `libtool`.
+
+  Using MacPorts:
+  ```shell
+  sudo port install libtool autoconf automake
+  ```
+
+  Using Homebrew:
+  ```shell
+  brew install libtool autoconf automake
+  ```
+  
+  In case you want to build the documentation, install `doxygen` using the corresponding install command from above.
+  
+  If you want to build Python bindings, you need to install cython:
+  ```shell
+  pip3 install cython
+  ```
+
+  You might need to set a few environment variables if building of the Python bindings fail. For example, the [automated build via GitHub actions](https://github.com/libimobiledevice/libplist/blob/master/.github/workflows/build.yml)
+  is setting the following environment variables:
+  ```shell
+  PYTHON3_BIN=`xcrun -f python3`
+  export PYTHON=$PYTHON3_BIN
+  PYTHON_VER=`$PYTHON3_BIN -c "import distutils.sysconfig; print(distutils.sysconfig.get_config_var('VERSION'))"`
+  PYTHON_EXEC_PREFIX=`$PYTHON3_BIN -c "import distutils.sysconfig; print(distutils.sysconfig.get_config_var('exec_prefix'))"`
+  PYTHON_LIBS_PATH=$PYTHON_EXEC_PREFIX/lib
+  PYTHON_FRAMEWORK_PATH=$PYTHON_EXEC_PREFIX/Python3
+  export PYTHON_LIBS="-L$PYTHON_LIBS_PATH -lpython$PYTHON_VER"
+  export PYTHON_EXTRA_LDFLAGS="-Wl,-stack_size,1000000  -framework CoreFoundation $PYTHON_FRAMEWORK_PATH"
+  ```
+
+* #### Windows: MSYS2
+
+  [MSYS2](https://www.msys2.org/) is the preferred way of compiling this project on Windows. Download the MSYS2 installer
+  and follow the installation steps.
+
+  It is recommended to use the _MSYS2 MinGW 64-bit_ shell. Run it and make sure the required dependencies are installed:
+
+  ```shell
+  pacman -S base-devel \
+        git \
+        mingw-w64-x86_64-gcc \
+        make \
+        libtool \
+        autoconf \
+        automake-wrapper
+  ```
+  NOTE: You can use a different shell and different compiler according to your needs. Adapt the above command accordingly.
+
+  If you want to optionally build Python bindings, you need to also install `cython`
+  and make sure you have a working python environment.
+
+  ```shell
+  pacman -S cython
+  ```
+
+### Configuring the source tree
+
+You can build the source code from a git checkout, or from a `.tar.bz2` release tarball from [Releases](https://github.com/libimobiledevice/libplist/releases).
+Before we can build it, the source tree has to be configured for building. The steps depend on where you got the source from.
+
+* #### From git
+
+  If you haven't done already, clone the actual project repository and change into the directory.
+  ```shell
+  git clone https://github.com/libimobiledevice/libplist.git
+  cd libplist
+  ```
+
+  Configure the source tree for building:
+  ```shell
+  ./autogen.sh
+  ```
+
+* #### From release tarball (.tar.bz2)
+
+  When using an official [release tarball](https://github.com/libimobiledevice/libplist/releases) (`libplist-x.y.z.tar.bz2`)
+  the procedure is slightly different.
+
+  Extract the tarball:
+  ```shell
+  tar xjf libplist-x.y.z.tar.bz2
+  cd libplist-x.y.z
+  ```
+
+  Configure the source tree for building:
+  ```shell
+  ./configure
+  ```
+
+Both `./configure` and `./autogen.sh` (which generates and calls `configure`) accept a few options, for example `--enable-debug` to allow
+printing debug messages in the final product, or `--without-cython` to skip building the Python bindings.
+You can simply pass them like this:
 
-If you want to optionally build the documentation or Python bindings use:
 ```shell
-sudo apt-get install \
-        doxygen \
-        cython3
+./autogen.sh --prefix=/usr/local --enable-debug --without-cython
 ```
-
-Then clone the actual project repository:
+or
 ```shell
-git clone https://github.com/libimobiledevice/libplist.git
-cd libplist
+./configure --prefix=/usr/local --enable-debug
+```
+
+Once the command is successful, the last few lines of output will look like this:
+```
+[...]
+config.status: creating config.h
+config.status: executing depfiles commands
+config.status: executing libtool commands
+
+Configuration for libplist 2.3.1:
+-------------------------------------------
+
+  Install prefix ..........: /usr/local
+  Debug code ..............: yes
+  Python bindings .........: yes
+
+  Now type 'make' to build libplist 2.3.1,
+  and then 'make install' for installation.
 ```
 
-Now you can build and install it:
+### Building and installation
+
+If you followed all the steps successfully, and `autogen.sh` or `configure` did not print any errors,
+you are ready to build the project. This is simply done with
+
 ```shell
-./autogen.sh
 make
+```
+
+If no errors are emitted, you can go ahead and install it with:
+```shell
 sudo make install
 ```
+When using a user-writable destination directory, or run from MinGW shell, you would just run `make install`, without sudo.
 
 ## Usage
 
-Then simply run:
+Usage is simple; `libplist` has a straight-forward API. It is used in [libimobiledevice](https://github.com/libimobiledevice/libimobiledevice)
+and [corresponding projects](https://github.com/libimobiledevice/).
+
+Furthermore, it comes with a command line utility `plistutil` that is really easy to use:
 ```shell
 plistutil -i foobar.plist -o output.plist
 ```
@@ -68,13 +201,16 @@ format - use the `-f` command line switch:
 ```shell
 plistutil -i input.plist -f json
 ```
-This will convert input.plist, regardless of the input format, to JSON. The
+This will convert `input.plist`, regardless of the input format, to JSON. The
 code auto-detects the input format and parses it accordingly.
 
 Please consult the usage information or manual page for a full documentation of
 available command line options:
 ```shell
 plistutil --help
+```
+or
+```shell
 man plistutil
 ```
 
@@ -95,8 +231,6 @@ Please make sure your contribution adheres to:
 * Try to split larger changes into individual commits of a common domain
 * Use your real name and a valid email address for your commits
 
-We are still working on the guidelines so bear with us!
-
 ## Links
 
 * Homepage: https://libimobiledevice.org/
@@ -119,4 +253,5 @@ iPadOS, tvOS, watchOS, and macOS are trademarks of Apple Inc.
 This project is an independent software library and has not been authorized,
 sponsored, or otherwise approved by Apple Inc.
 
-README Updated on: 2023-11-26
+README Updated on: 2024-02-13
+