summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--README.md165
1 files changed, 140 insertions, 25 deletions
diff --git a/README.md b/README.md
index 812ab9e..ef70f66 100644
--- 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