Skip to content

Commit

Permalink
Improve README.md with features, installation and usage sections
Browse files Browse the repository at this point in the history
  • Loading branch information
@FunkyM @nikias
FunkyM authored and nikias committed Jun 12, 2020
1 parent f56a65f commit dbb127e
Showing 1 changed file with 129 additions and 35 deletions.
164 changes: 129 additions & 35 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,35 +1,86 @@
# libimobiledevice

## About

A library to communicate with services of Apple iOS devices using native
protocols.

## Requirements

Development Packages of:
* OpenSSL or GnuTLS
* libplist
* libusbmuxd

Software:
* usbmuxd (OSS or Apple's version)
* make
* autoheader
* automake
* autoconf
* libtool
* pkg-config
* gcc or clang
*A library to communicate with services on iOS devices using native protocols.*

## Features

libimobiledevice is a cross-platform software library that talks the protocols
to interact with iOS devices.

Unlike other projects, it does not depend on using any existing proprietary
libraries and does not require jailbreaking.

Some key features are:

- **Interface**: Implements many high-level interfaces for device services
- **Implementation**: Object oriented architecture and service abstraction layer
- **Cross-Platform:** Tested on Linux, macOS, Windows and Android platforms
- **Utilities**: Provides various command-line utilities for device services
- **SSL**: Allows choosing between OpenSSL or GnuTLS to handle SSL communication
- **Network**: Supports network connections with "WiFi sync" enabled devices
- **Python:** Provides Cython based bindings for Python

The implemented interfaces of many device service protocols allow applications
to:

* Access filesystem of a device
* Access documents of file sharing apps
* Retrieve information about a device and modify various settings
* Backup and restore the device in a native way compatible with iTunes
* Manage app icons arrangement on the device
* Install, remove, list and basically manage apps
* Activate a device using official serviers
* Manage contacts, calendars, notes and bookmarks
* Retrieve and remove crashreports
* Retrieve various diagnostics information
* Establish a debug connection for app debugging
* Mount filesystem images
* Forward device notifications
* Manage device provisioning
* Take screenshots from the device screen (requires mounted developer image)
* Simulate changed geolocation of the device (requires mounted developer image)
* Relay the syslog of the device
* Expose a connection for WebKit remote debugging

... and much more.

The library is in development since August 2007 with the goal to bring support
for these devices to the Linux Desktop.

## Installation / Getting started

### Debian / Ubuntu Linux

First install all required dependencies and build tools:
```shell
sudo apt-get install \
build-essential \
checkinstall \
git \
autoconf \
automake \
libtool-bin \
libplist-dev \
libusbmuxd-dev \
libssl-dev \
usbmuxd
```

Optional:
* cython (Python bindings)
* doxygen (Documentation)
If you want to optionally build the documentation or Python bindings use:
```shell
sudo apt-get install \
doxygen \
cython
```

## Installation
Then clone the actual project repository:
```shell
git clone https://github.com/libimobiledevice/libimobiledevice.git
cd libimobiledevice
```

To compile run:
```bash
Now you can build and install it:
```shell
./autogen.sh
make
sudo make install
Expand All @@ -49,20 +100,63 @@ By default, OpenSSL will be used. If you prefer GnuTLS, configure with
./autogen.sh --disable-openssl
```

## Who/What/Where?
## Usage

Documentation about using the library in your application is not available yet.
The "hacker way" for now is to look at the implementation of the included
utilities.

### Utilities

The library bundles the following command-line utilities in the tools directory:

| Utility | Description |
| -------------------------- | ------------------------------------------------------------------ |
| `idevice_id` | List attached devices or print device name of given device |
| `idevicebackup` | Create or restore backup for devices (legacy) |
| `idevicebackup2` | Create or restore backups for devices running iOS 4 or later |
| `idevicecrashreport` | Retrieve crash reports from a device |
| `idevicedate` | Display the current date or set it on a device |
| `idevicedebug` | Interact with the debugserver service of a device |
| `idevicedebugserverproxy` | Proxy a debugserver connection from a device for remote debugging |
| `idevicediagnostics` | Interact with the diagnostics interface of a device |
| `ideviceenterrecovery` | Make a device enter recovery mode |
| `ideviceimagemounter` | Mount disk images on the device |
| `ideviceinfo` | Show information about a connected device |
| `idevicename` | Display or set the device name |
| `idevicenotificationproxy` | Post or observe notifications on a device |
| `idevicepair` | Manage host pairings with devices and usbmuxd |
| `ideviceprovision` | Manage provisioning profiles on a device |
| `idevicescreenshot` | Gets a screenshot from the connected device |
| `idevicesetlocation` | Simulate location on device |
| `idevicesyslog` | Relay syslog of a connected device |

Please consult the usage information or manual pages of each utility for a
documentation of available command line options and usage examples like this:
```shell
ideviceinfo --help
man ideviceinfo
```

## Links

* Home: https://libimobiledevice.org/
* Code: `git clone https://git.libimobiledevice.org/libimobiledevice.git`
* Code (Mirror): `git clone https://github.com/libimobiledevice/libimobiledevice.git`
* Tickets: https://github.com/libimobiledevice/libimobiledevice/issues
* Homepage: https://libimobiledevice.org/
* Repository: https://git.libimobiledevice.org/libimobiledevice.git
* Repository (Mirror): https://github.com/libimobiledevice/libimobiledevice.git
* Issue Tracker: https://github.com/libimobiledevice/libimobiledevice/issues
* Mailing List: https://lists.libimobiledevice.org/mailman/listinfo/libimobiledevice-devel
* Twitter: https://twitter.com/libimobiledev

## 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),
also included in the repository in the `COPYING` file.

## Credits

Apple, iPhone, iPod, and iPod Touch are trademarks of Apple Inc.

libimobiledevice is an independent software library and has not been
authorized, sponsored, or otherwise approved by Apple Inc.
This project is an independent software and has not been authorized, sponsored,
or otherwise approved by Apple Inc.

README Updated on: 2020-06-08
README Updated on: 2020-06-12

0 comments on commit dbb127e

Please sign in to comment.