diff options
| -rw-r--r-- | README.md | 223 |
1 files changed, 178 insertions, 45 deletions
@@ -4,6 +4,21 @@  +## 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 |