README

Chafa
=====

Chafa is a command-line utility that converts image data, including
animated GIFs, into graphics formats or ANSI/Unicode character art suitable
for display in a terminal. It has broad feature support, allowing it to be
used on devices ranging from historical teleprinters to modern terminal
emulators and everything in between.

The core functionality is provided by a C library with a public,
well-documented API.

Both library and frontend tools are covered by the Lesser GPL license,
version 3 or later (LGPLv3+).

For the most up-to-date information, please see https://hpjansson.org/chafa/

Installing with package manager
-------------------------------

Chafa is available as packages for many software distributions. A few are
listed below, along with their command-line installation instructions:

Arch Linux .... pacman -S chafa
Brew .......... brew install chafa
Debian ........ apt install chafa
Fedora ........ dnf install chafa
FreeBSD ....... pkg install chafa
Gentoo ........ emerge media-gfx/chafa
Guix .......... guix install chafa
Kali Linux .... apt install chafa
MacPorts ...... port install chafa
OpenBSD ....... pkg_add chafa
openSUSE ...... zypper in chafa
Ubuntu ........ apt install chafa

On Windows, Chafa can be installed via Scoop and Winget:

Scoop ....... scoop install chafa
Winget ....... winget install hpjansson.Chafa

See https://hpjansson.org/chafa/download/ for more.

Installing from tarball
-----------------------

You will need GCC, make and the GLib development package installed to
compile Chafa from a release tarball. If you want to build the
command-line tool `chafa` and not just the library, you will
additionally need the ImageMagick development packages.

Prebuilt documentation is included in the release tarball, and you do not
need gtk-doc unless you want to make changes/rebuild it.

After unpacking, cd to the toplevel directory and issue the following
shell commands:

$ ./configure
$ make
$ sudo make install

Installing from git repository
------------------------------

You will need GCC, make, Autoconf, Automake, Libtool and the GLib
development package installed to compile Chafa from its git repository. If
you want to build the command-line tool `chafa` and not just the library,
you will additionally need development packages for:

* FreeType2
* libjpeg (optional)
* librsvg (optional)
* libtiff (optional)
* libwebp (optional)
* ImageMagick (optional, deprecated)

If you want to build documentation, you will also need gtk-doc.

Start by cloning the repository:

$ git clone https://github.com/hpjansson/chafa.git

Then cd to the toplevel directory and issue the following shell commands:

$ ./autogen.sh
$ make
$ sudo make install

Python bindings
---------------

Erica Ferrua Edwardsdóttir maintains excellent Python bindings for Chafa. If
Python's your thing, check them out. They are easy to use and come with a
detailed tutorial:

https://chafapy.mage.black/