Skip to content

Commit

Permalink
Updated README
Browse files Browse the repository at this point in the history
  • Loading branch information
@nikias
nikias committed Feb 13, 2024
1 parent 082b69d commit 122263b
Showing 1 changed file with 157 additions and 22 deletions.
179 changes: 157 additions & 22 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Expand All @@ -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
```

Expand All @@ -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/
Expand All @@ -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

0 comments on commit 122263b

Please sign in to comment.