Updated README

README.md

@@ -4,6 +4,21 @@
 
 ![](https://github.com/libimobiledevice/idevicerestore/actions/workflows/build.yml/badge.svg)
 
+## Table of Contents
+- [Features](#features)
+- [Building](#building)
+ - [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)
+- [Usage](#usage)
+- [Contributing](#contributing)
+- [Links](#links)
+- [License](#license)
+- [Credits](#credits)
+
 ## Features
 
 The idevicerestore application is a full reimplementation of all granular steps
@@ -33,56 +48,176 @@ Use with caution and make sure to backup your data before trying to restore.
 
 **In any case, usage is at your own risk.**
 
-## Installation / Getting started
-
-### Debian / Ubuntu Linux
+## Building
+
+### 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.
+
+#### 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 \
+ libreadline-dev \
+ libusb-1.0-0-dev \
+ libplist-dev \
+ libimobiledevice-dev \
+ libimobiledevice-glue-dev \
+ libtatsu-dev \
+ libcurl4-openssl-dev \
+ libssl-dev \
+ libzip-dev \
+ zlib1g-dev
+ ```
+ NOTE: [libtatsu](https://github.com/libimobiledevice/libtatsu) (and thus `libtatsu-dev`)
+ is a new library that was just published recently, you have to
+ [build it from source](https://github.com/libimobiledevice/libtatsu?tab=readme-ov-file#building).
+ Also, other `*-dev` packages might not be available for your distribution,
+ so you will have to build these packages on your own as well.
+
+#### macOS
+
+* Make sure the Xcode command line tools are installed.
+
+ **Option 1**:
+ The easiest way to build and install `idevicerestore` for macOS is using
+ the following build script which will do the work for you, it will build
+ and install all required dependencies:
+ ```bash
+ mkdir -p limd-build
+ cd limd-build
+ curl -o ./limd-build-macos.sh -L https://is.gd/limdmacos
+ bash ./limd-build-macos.sh
+ ```
+ Follow the prompts of the script and you should have a working `idevicerestore`
+ available.
+
+ **Option 2**:
+ 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
+ ```
+
+ `idevicerestore` has a few dependencies from the libimobiledevice project.
+ You will have to build and install the following:
+ * [libplist](https://github.com/libimobiledevice/libplist)
+ * [libimobiledevice-glue](https://github.com/libimobiledevice/libimobiledevice-glue)
+ * [libusbmuxd](https://github.com/libimobiledevice/libusbmuxd)
+ * [libimobiledevice](https://github.com/libimobiledevice/libimobiledevice)
+ * [libirecovery](https://github.com/libimobiledevice/libirecovery)
+ * [libtatsu](https://github.com/libimobiledevice/libtatsu)
+
+ Check their `README.md` for building and installation instructions.
+
+#### 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
+ ```
+ NOTE: You can use a different shell and different compiler according to your needs. Adapt the above command accordingly.
+
+ `idevicerestore` has a few dependencies from the libimobiledevice project.
+ You will have to build and install the following:
+ * [libplist](https://github.com/libimobiledevice/libplist)
+ * [libimobiledevice-glue](https://github.com/libimobiledevice/libimobiledevice-glue)
+ * [libusbmuxd](https://github.com/libimobiledevice/libusbmuxd)
+ * [libimobiledevice](https://github.com/libimobiledevice/libimobiledevice)
+ * [libirecovery](https://github.com/libimobiledevice/libirecovery)
+ * [libtatsu](https://github.com/libimobiledevice/libtatsu)
+
+ Check their `README.md` for building and installation instructions.
+
+
+### 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/idevicerestore/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/idevicerestore.git
+ cd idevicerestore
+ ```
+
+ Configure the source tree for building:
+ ```shell
+ ./autogen.sh
+ ```
+
+* **From release tarball (.tar.bz2)**
+
+ When using an official [release tarball](https://github.com/libimobiledevice/idevicerestore/releases) (`idevicerestore-x.y.z.tar.bz2`)
+ the procedure is slightly different.
+
+ Extract the tarball:
+ ```shell
+ tar xjf idevicerestore-x.y.z.tar.bz2
+ cd idevicerestore-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:
 
-First install all required dependencies and build tools:
 ```shell
-sudo apt-get install \
- build-essential \
- pkg-config \
- checkinstall \
- git \
- autoconf \
- automake \
- libtool-bin \
- libreadline-dev \
- libusb-1.0-0-dev \
- libplist-dev \
- libimobiledevice-dev \
- libimobiledevice-glue-dev \
- libcurl4-openssl-dev \
- libssl-dev \
- libzip-dev \
- zlib1g-dev
+./autogen.sh --prefix=/usr/local
 ```
-
-Then clone, build and install [libirecovery](https://github.com/libimobiledevice/libirecovery.git) which is not yet packaged:
+or
 ```shell
-git clone https://github.com/libimobiledevice/libirecovery.git
-cd libirecovery
-./autogen.sh
-make
-sudo make install
-cd ..
+./configure --prefix=/usr/local
 ```
 
-If the configure processes indicates old or missing libraries, your distribution
-might not have yet packaged the latest versions. In that case you will have to
-clone [these libraries](https://github.com/libimobiledevice/) separately and repeat the process in order to proceed.
-
-Continue with cloning the actual project repository:
-```shell
-git clone https://github.com/libimobiledevice/idevicerestore.git
-cd idevicerestore
+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
 
-Now you can build and install it:
-```shell
-./autogen.sh
-make
-sudo make install
+Configuration for idevicerestore 1.1.0:
+-------------------------------------------
+
+ Install prefix: .........: /usr/local
+
+ Now type 'make' to build idevicerestore 1.1.0,
+ and then 'make install' for installation.
 ```
 
 **Important**
@@ -142,8 +277,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/
@@ -166,4 +299,4 @@ iPadOS, tvOS, watchOS, and macOS are trademarks of Apple Inc.
 This project is an independent software application and has not been
 authorized, sponsored, or otherwise approved by Apple Inc.
 
-README Updated on: 2022-04-04
+README Updated on: 2024-06-19