Updated README

README.md

@@ -13,7 +13,7 @@ Besides that it comes with a number of string, file, and plist helper
 functions, as well as some other commonly used code that was originally
 duplicated in the dedicated projects.
 
-Test on Linux, macOS, Windows.
+Tested on Linux, macOS, and Windows.
 
 ## Projects using this library
 
@@ -23,48 +23,177 @@ Test on Linux, macOS, Windows.
 - [libirecovery](https://github.com/libimobiledevice/libirecovery)
 - [idevicerestore](https://github.com/libimobiledevice/idevicerestore)
 
-## Installation / Getting started
+## Building
 
-### Debian / Ubuntu Linux
+### Quick access
+
+* [Prerequisites](#prerequisites)
+  * [Linux (Debian/Ubuntu based)](#linux-debianubuntu-based)
+  * [macOS](#macos)
+  * [Windows](#windows)
+* [Configuring the source tree](#configuring-the-source-tree)
+* [Building and installation](#building-and-installation)
+
+### Prerequisites
+
+You need to have a working compiler (gcc/clang) and development environent
+available. This project uses autotools for the build process, allowing to
+have common build steps across different platforms.
+Only the prerequisites differ and they are described in this section.
+
+libimobiledevice-glue requires [libplist](https://github.com/libimobiledevice/libplist).
+Check the [Building](https://github.com/libimobiledevice/libplist?tab=readme-ov-file#building)
+section of the README on how to build it. Note that some platforms might have it as a package.
+
+* #### Linux (Debian/Ubuntu based)
+
+  Install all required dependencies and build tools:
+  ```shell
+  sudo apt-get install \
+  	build-essential \
+  	pkg-config \
+  	checkinstall \
+  	git \
+  	autoconf \
+  	automake \
+  	libtool-bin \
+  	libplist-dev
+  ```
+
+  In case libplist-dev is not available, you can manually build and install it. See note above.
+
+* #### 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`, `libtool`, etc.
+
+  Using MacPorts:
+  ```shell
+  sudo port install libtool autoconf automake pkgconfig
+  ```
+
+  Using Homebrew:
+  ```shell
+  brew install libtool autoconf automake pkg-config
+  ```
+
+* #### Windows
+
+  Using [MSYS2](https://www.msys2.org/) is the official 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 \
+  	pkg-config
+  ```
+  NOTE: You can use a different shell and different compiler according to your needs. Adapt the above command accordingly.
+
+### 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/libimobiledevice-glue/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.
+
+Since libimobiledevice-glue depends on other packages, you should set the pkg-config environment variable `PKG_CONFIG_PATH`
+accordingly. Make sure to use a path with the same prefix as the dependencies. If they are installed in `/usr/local` you would do
 
-First install all required dependencies and build tools:
 ```shell
-sudo apt-get install \
-	build-essential \
-	pkg-config \
-	checkinstall \
-	git \
-	autoconf \
-	automake \
-	libtool-bin \
-	libplist-dev
+export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
 ```
 
-Then clone the actual project repository:
+* #### 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/libimobiledevice-glue
+  cd libimobiledevice-glue
+  ```
+
+  Configure the source tree for building:
+  ```shell
+  ./autogen.sh
+  ```
+
+* #### From release tarball (.tar.bz2)
+
+  When using an official [release tarball](https://github.com/libimobiledevice/libimobiledevice-glue/releases) (`libimobiledevice-glue-x.y.z.tar.bz2`)
+  the procedure is slightly different.
+
+  Extract the tarball:
+  ```shell
+  tar xjf libimobiledevice-glue-x.y.z.tar.bz2
+  cd libimobiledevice-glue-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 `--prefix` to allow
+building for a different target folder. You can simply pass them like this:
+
 ```shell
-git clone https://github.com/libimobiledevice/libimobiledevice-glue.git
-cd libimobiledevice-glue
+./autogen.sh --prefix=/usr/local
 ```
+or
+```shell
+./configure --prefix=/usr/local
+```
+
+Once the command is successful, the last few lines of output will look like this:
+```
+[...]
+config.status: creating config.h
+config.status: config.h is unchanged
+config.status: executing depfiles commands
+config.status: executing libtool commands
+
+Configuration for libimobiledevice-glue 1.0.1:
+-------------------------------------------
+
+  Install prefix: .........: /usr/local
+
+  Now type 'make' to build libimobiledevice-glue 1.0.1,
+  and then 'make install' for installation.
+```
+
+### 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
 
-Now you can build and install it:
 ```shell
-./autogen.sh
 make
-sudo make install
 ```
 
-If you require a custom prefix or other option being passed to `./configure`
-you can pass them directly to `./autogen.sh` like this:
-```bash
-./autogen.sh --prefix=/opt/local
-make
+If no errors are emitted you are ready to install. Depending on if the current
+user has permissions to write to the destination directory or not, you would
+either run
+```shell
+make install
+```
+_OR_
+```shell
 sudo make install
 ```
 
+If you are on Linux, you want to run `sudo ldconfig` after installation to
+make sure the installed libraries are made available.
+
 ## Usage
 
 This library is directly used by libusbmuxd, libimobiledevice, etc., so there
-is no need to do anything in particular.
+is no need to do anything in particular. Feel free to use it in your project,
+check the header files for available functions. A documentation might be added
+later.
 
 ## Contributing
 
@@ -104,4 +233,4 @@ iPadOS, tvOS, watchOS, and macOS are trademarks of Apple Inc.
 This project is an independent software and has not been authorized, sponsored,
 or otherwise approved by Apple Inc.
 
-README Updated on: 2022-04-04
+README Updated on: 2024-02-17