Skip to content

Commit

Permalink
Updated README
Browse files Browse the repository at this point in the history
  • Loading branch information
@nikias
nikias committed Jun 19, 2024
1 parent 4117b89 commit a4cf7e2
Showing 1 changed file with 178 additions and 45 deletions.
223 changes: 178 additions & 45 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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**
Expand Down Expand Up @@ -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/
Expand All @@ -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

0 comments on commit a4cf7e2

Please sign in to comment.