diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 193 |
1 files changed, 164 insertions, 29 deletions
@@ -5,6 +5,21 @@ Library with common code used by the libraries and tools around the  +## 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 main functionality provided by this library are **socket** helper @@ -13,7 +28,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 +38,167 @@ Test on Linux, macOS, Windows. - [libirecovery](https://github.com/libimobiledevice/libirecovery) - [idevicerestore](https://github.com/libimobiledevice/idevicerestore) -## 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. + +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 + ``` -### Debian / Ubuntu Linux +#### 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 +./autogen.sh --prefix=/usr/local +``` +or ```shell -git clone https://github.com/libimobiledevice/libimobiledevice-glue.git -cd libimobiledevice-glue +./configure --prefix=/usr/local ``` -Now you can build and install it: +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 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 + ```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 for installation. Depending on whether +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 @@ -93,7 +227,7 @@ Please make sure your contribution adheres to: ## License -This library and utilities are licensed under the [GNU Lesser General Public License v2.1](https://www.gnu.org/licenses/lgpl-2.1.en.html), +This library is licensed under the [GNU Lesser General Public License v2.1](https://www.gnu.org/licenses/lgpl-2.1.en.html), also included in the repository in the `COPYING` file. ## Credits @@ -101,7 +235,8 @@ also included in the repository in the `COPYING` file. Apple, iPhone, iPad, iPod, iPod Touch, Apple TV, Apple Watch, Mac, iOS, 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. +This project is an independent software library and has not been authorized, +sponsored, or otherwise approved by Apple Inc. + +README Updated on: 2024-02-21 -README Updated on: 2022-04-04 |