summaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md179
1 files changed, 157 insertions, 22 deletions
diff --git a/README.md b/README.md
index 6fa3713..b59d37f 100644
--- a/README.md
+++ b/README.md
@@ -16,47 +16,180 @@ Some key features are:
- **Formats:** Supports binary, XML, JSON, and OpenStep format
- **Utility:** Provides a `plistutil` utility for the command-line
- **Python:** Provides Cython based bindings for Python
-- **Tested:** Uses fuzzing and data compliance tests
+- **Tested:** Uses fuzzing ([OSS-Fuzz](https://github.com/google/oss-fuzz)) and data compliance tests
- **Efficient:** Lean library with performance and resources in mind
-## Installation / Getting started
+## Building
-### Debian / Ubuntu Linux
+You need to have a working compiler and development environent available.
-First install all required dependencies and build tools:
-```shell
-sudo apt-get install \
+### Prerequisites
+
+* #### Debian/Ubuntu based Linux
+
+ Install all required dependencies and build tools:
+ ```shell
+ sudo apt-get install \
build-essential \
checkinstall \
git \
autoconf \
automake \
libtool-bin
-```
+ ```
+
+ If you want to optionally build the documentation or Python bindings use:
+ ```shell
+ sudo apt-get install \
+ doxygen \
+ cython3
+ ```
+
+* #### 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`, and `libtool`.
+
+ Using MacPorts:
+ ```shell
+ sudo port install libtool autoconf automake
+ ```
+
+ Using Homebrew:
+ ```shell
+ brew install libtool autoconf automake
+ ```
+
+ In case you want to build the documentation, install `doxygen` using the corresponding install command from above.
+
+ If you want to build Python bindings, you need to install cython:
+ ```shell
+ pip3 install cython
+ ```
+
+ You might need to set a few environment variables if building of the Python bindings fail. For example, the [automated build via GitHub actions](https://github.com/libimobiledevice/libplist/blob/master/.github/workflows/build.yml)
+ is setting the following environment variables:
+ ```shell
+ PYTHON3_BIN=`xcrun -f python3`
+ export PYTHON=$PYTHON3_BIN
+ PYTHON_VER=`$PYTHON3_BIN -c "import distutils.sysconfig; print(distutils.sysconfig.get_config_var('VERSION'))"`
+ PYTHON_EXEC_PREFIX=`$PYTHON3_BIN -c "import distutils.sysconfig; print(distutils.sysconfig.get_config_var('exec_prefix'))"`
+ PYTHON_LIBS_PATH=$PYTHON_EXEC_PREFIX/lib
+ PYTHON_FRAMEWORK_PATH=$PYTHON_EXEC_PREFIX/Python3
+ export PYTHON_LIBS="-L$PYTHON_LIBS_PATH -lpython$PYTHON_VER"
+ export PYTHON_EXTRA_LDFLAGS="-Wl,-stack_size,1000000 -framework CoreFoundation $PYTHON_FRAMEWORK_PATH"
+ ```
+
+* #### Windows: MSYS2
+
+ [MSYS2](https://www.msys2.org/) is the preferred 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.
+
+ If you want to optionally build Python bindings, you need to also install `cython`
+ and make sure you have a working python environment.
+
+ ```shell
+ pacman -S cython
+ ```
+
+### 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/libplist/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/libplist.git
+ cd libplist
+ ```
+
+ Configure the source tree for building:
+ ```shell
+ ./autogen.sh
+ ```
+
+* #### From release tarball (.tar.bz2)
+
+ When using an official [release tarball](https://github.com/libimobiledevice/libplist/releases) (`libplist-x.y.z.tar.bz2`)
+ the procedure is slightly different.
+
+ Extract the tarball:
+ ```shell
+ tar xjf libplist-x.y.z.tar.bz2
+ cd libplist-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 `--enable-debug` to allow
+printing debug messages in the final product, or `--without-cython` to skip building the Python bindings.
+You can simply pass them like this:
-If you want to optionally build the documentation or Python bindings use:
```shell
-sudo apt-get install \
- doxygen \
- cython3
+./autogen.sh --prefix=/usr/local --enable-debug --without-cython
```
-
-Then clone the actual project repository:
+or
```shell
-git clone https://github.com/libimobiledevice/libplist.git
-cd libplist
+./configure --prefix=/usr/local --enable-debug
+```
+
+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 libplist 2.3.1:
+-------------------------------------------
+
+ Install prefix ..........: /usr/local
+ Debug code ..............: yes
+ Python bindings .........: yes
+
+ Now type 'make' to build libplist 2.3.1,
+ and then 'make install' for installation.
```
-Now you can build and install it:
+### 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
+```
+
+If no errors are emitted, you can go ahead and install it with:
+```shell
sudo make install
```
+When using a user-writable destination directory, or run from MinGW shell, you would just run `make install`, without sudo.
## Usage
-Then simply run:
+Usage is simple; `libplist` has a straight-forward API. It is used in [libimobiledevice](https://github.com/libimobiledevice/libimobiledevice)
+and [corresponding projects](https://github.com/libimobiledevice/).
+
+Furthermore, it comes with a command line utility `plistutil` that is really easy to use:
```shell
plistutil -i foobar.plist -o output.plist
```
@@ -68,13 +201,16 @@ format - use the `-f` command line switch:
```shell
plistutil -i input.plist -f json
```
-This will convert input.plist, regardless of the input format, to JSON. The
+This will convert `input.plist`, regardless of the input format, to JSON. The
code auto-detects the input format and parses it accordingly.
Please consult the usage information or manual page for a full documentation of
available command line options:
```shell
plistutil --help
+```
+or
+```shell
man plistutil
```
@@ -95,8 +231,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/
@@ -119,4 +253,5 @@ iPadOS, tvOS, watchOS, and macOS are trademarks of Apple Inc.
This project is an independent software library and has not been authorized,
sponsored, or otherwise approved by Apple Inc.
-README Updated on: 2023-11-26
+README Updated on: 2024-02-13
+