summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorGravatar Martin Szulecki2020-06-13 00:19:35 +0200
committerGravatar Nikias Bassen2020-06-13 01:56:10 +0200
commitdbb127e24c2451bdea93269545692fee9e5a6287 (patch)
tree4ee6c10db5695b1f41e57664dafed9cdda1880ee
parentf56a65f7bc08de0cd9bc5c1e4683b1d0c671b767 (diff)
downloadlibimobiledevice-dbb127e24c2451bdea93269545692fee9e5a6287.tar.gz
libimobiledevice-dbb127e24c2451bdea93269545692fee9e5a6287.tar.bz2
Improve README.md with features, installation and usage sections
-rw-r--r--README.md164
1 files changed, 129 insertions, 35 deletions
diff --git a/README.md b/README.md
index 294c7f0..89dea3c 100644
--- a/README.md
+++ b/README.md
@@ -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
@@ -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