Updated README

libimobiledevice · Mar 27, 2024 · 570c0c2 · 570c0c2
1 parent 499fb0c
commit 570c0c2
Showing 1 changed file with 140 additions and 25 deletions.
diff --git a/README.md b/README.md
@@ -4,6 +4,21 @@
 
 ![](https://github.com/libimobiledevice/libusbmuxd/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
 
 This project is a client library to multiplex connections from and to iOS
@@ -32,36 +47,138 @@ Some key features are:
 Furthermore the Linux build optionally provides support using inotify if
 available.
 
-## Installation / Getting started
+## 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.
+
+libusbmuxd requires [libplist](https://github.com/libimobiledevice/libplist) and [libimobiledevice-glue](https://github.com/libimobiledevice/libimobiledevice-glue). On Linux, it also requires [usbmuxd](https://github.com/libimobiledevice/usbmuxd) installed on the system, while macOS has its own copy and on Windows AppleMobileDeviceSupport package provides it.
+Check [libplist's Building](https://github.com/libimobiledevice/libplist?tab=readme-ov-file#building) and [libimobiledevice-glue's Building](https://github.com/libimobiledevice/libimobiledevice-glue?tab=readme-ov-file#building)
+section of the respective README on how to build them. Note that some platforms might have them 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 \
+  	libimobiledevice-glue-dev \
+  	usbmuxd
+  ```
+  In case libplist-dev, libimobiledevice-glue-dev, or usbmuxd are not available, you can manually build and install them. 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/libusbmuxd/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.
 
-### Debian / Ubuntu Linux
+Since libusbmuxd 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 \
-	libimobiledevice-glue-dev \
-	usbmuxd
+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/libusbmuxd
+  cd libusbmuxd
+  ```
+
+  Configure the source tree for building:
+  ```shell
+  ./autogen.sh
+  ```
+
+* **From release tarball (.tar.bz2)**
+
+  When using an official [release tarball](https://github.com/libimobiledevice/libusbmuxd/releases) (`libusbmuxd-x.y.z.tar.bz2`)
+  the procedure is slightly different.
+
+  Extract the tarball:
+  ```shell
+  tar xjf libusbmuxd-x.y.z.tar.bz2
+  cd libusbmuxd-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/libusbmuxd.git
-cd libusbmuxd
+./autogen.sh --prefix=/usr/local
 ```
-
-Now you can build and install it:
+or
 ```shell
-./autogen.sh
-make
-sudo make install
+./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: executing depfiles commands
+config.status: executing libtool commands
+
+Configuration for libusbmuxd 2.1.0:
+-------------------------------------------
+
+  Install prefix: .........: /usr/local
+  inotify support (Linux) .: no
+
+  Now type 'make' to build libusbmuxd 2.1.0,
+  and then 'make install' for installation.
 ```
 
 ## Usage
@@ -138,8 +255,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/
@@ -164,4 +279,4 @@ 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: 2022-04-04
+README Updated on: 2024-03-27