diff options
| -rw-r--r-- | README.md | 179 |
1 files changed, 157 insertions, 22 deletions
@@ -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 + |