diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 178 |
1 files changed, 100 insertions, 78 deletions
@@ -1,136 +1,158 @@ -# feh -Imlib2 based image viewer ---- +# feh - Image Viewer and Cataloguer - * http://feh.finalrewind.org/ - * http://linuxbrit.co.uk/feh/ - * #feh on irc.oftc.net +**feh** is a light-weight, configurable and versatile image viewer. +It is aimed at command line users, but can also be started from graphical file +managers. Apart from viewing images, it can compile text and thumbnail +listings, show (un)loadable files, set X11 backgrounds, and more. -Dependencies ---- +Features include filelists, various image sorting modes, custom action scripts, +and image captions. feh can be controlled by configurable keyboard and mouse +shortcuts, terminal input and signals. When no file arguments or filelists are +specified, feh displays all files in the current directory. + +This README focuses on installation and contribution instructions. See the +[feh homepage](https://feh.finalrewind.org/) and the +[feh(1) manual](https://man.finalrewind.org/1/feh/) for usage instructions. + +## Dependencies * Imlib2 - * libcurl (disable with make curl=0) + * libcurl (disable with `curl=0`) * libpng * libX11 - * libXinerama (disable with make xinerama=0) + * libXt + * libXinerama (disable with `xinerama=0`) -If built with exif=1: +Only when building with `exif=1`: * libexif-dev * libexif12 -Recommended ---- - - * jpegtran (supplied by the jpeg library, for lossless image rotation) - * convert (supplied by ImageMagick, can be used to load unsupported formats) +Only when building with `magic=1`: -Installation ---- - -**For end users:** -```bash -$ make -$ sudo make install app=1 -``` - -**For package maintainers and users who do not want feh to install its -icons into /usr/share:** -```bash -$ make -$ sudo make install -``` - -**Explanation:** feh ships some icons and an X11 desktop entry, which allow it to -be used from file managers, desktop menus and similar. However, installing -icons to /usr/local/share/... does not seem to work reliable in all cases. -Because of this, when using "make install app=1", feh will install its icons -to /usr/share/..., even though they technically belong into /usr/local. + * libmagic +## Build Process -ZSH Completion for feh is available [here](http://git.finalrewind.org/zsh/plain/etc/completions/_feh) +feh has been packaged for a variety of distributions, including +[Arch Linux](https://archlinux.org/packages/extra/x86_64/feh/), +[Debian](https://packages.debian.org/search?keywords=feh&exact=1), +[FreeBSD](https://www.freshports.org/graphics/feh), and +[Ubuntu](https://packages.ubuntu.com/search?keywords=feh&exact=1). +You can configure, compile and install a custom version as follows. -Make flags ----------- +### Configuration -Flags can be used to control the build and installation process. +feh's build process uses make flags to enable/disable optional features and +fine-tune the build and installation process. It uses (hopefully) reasonable +defaults, so you can skip this section if you like. -e.g. +Make flags can be passed as **make** arguments or set as environment variables, +like so: ```bash -make flag=bool -``` -```bash -make install flag=bool +$ make flag=bool +$ make install flag=bool ``` or ```bash -export flag=bool -make && make install +$ export flag=bool +$ make && make install ``` -For example, `make xinerama=0 debug=1` will disable Xinerama support and produce a debug build. - -Available flags are: +The following flags are respected by the makefile. A default value of **1** +indicates that the corresponding feature is enabled by default. | Flag | Default value | Description | | :--- | :---: | :--- | -| app | 0 | install icons to /usr/share, regardless of `DESTDIR` and `PREFIX, and call gtk-update-icon-cache afterwards | -| cam | 0 | install deprecated feh-cam und gen-cam-menu scripts | -| curl | 1 | use libcurl to view http:// and similar images | +| app | 0 | install icons to /usr/share, regardless of `DESTDIR` and `PREFIX`, and call gtk-update-icon-cache afterwards | +| curl | 1 | use libcurl to view https:// and similar images | | debug | 0 | debug build, enables `--debug` | | exif | 0 | Builtin EXIF tag display support | | help | 0 | include help text (refers to the manpage otherwise) | +| inotify | 0 | enable inotify, needed for `--auto-reload` | | stat64 | 0 | Support CIFS shares from 64bit hosts on 32bit machines | +| magic | 0 | Use libmagic to filter unsupported file formats | +| mkstemps | 1 | Whether your libc provides `mkstemps()`. If set to 0, feh will be unable to load gif images via libcurl | +| verscmp | 1 | Whether your libc provides `strvercmp()`. If set to 0, feh will use an internal implementation. | | xinerama | 1 | Support Xinerama/XRandR multiscreen setups | -So, by default **libcurl** and **Xinerama** are enabled, the rest is disabled. +For example, `make xinerama=0 debug=1` will disable Xinerama support and +produce a debug build; libcurl and natural sorting support will remain enabled. -Additionally, the standard variables `PREFIX` and `DESTDIR` are supported. +Additionally, it supports the standard variables `CFLAGS`, `LDLIBS`, `PREFIX`, +and `DESTDIR`. -**PREFIX _(default: /usr)_** controls where the application and its data files +**PREFIX _(default: /usr/local)_** controls where the application and its data files will be installed. It must be set both during `make` and `make install`. **DESTDIR _(default: empty)_** sets the installation root during "make install". It is mostly useful for package maintainers. -**Note:** config.mk is designed so that in most cases, you can set environment -variables instead of editing it. E.g.: +**Note:** Defaults are specified in `config.mk`. It is designed so that in most +cases, you can set environment variables instead of editing it. E.g.: ```bash -CFLAGS='-g -Os' make +$ CFLAGS='-g -Os' make ``` ```bash -export DESTDIR=/tmp/feh PREFIX=/usr -make && make install +$ export DESTDIR=/tmp/feh PREFIX=/usr +$ make && make install ``` Builtin EXIF support is maintained by Dennis Real, [here](https://github.com/reald/feh). +### Installation -Testing (non-X) ---------------- +Add your own make flags to the following examples as needed. + +**For end users:** ```bash -$ make test +$ make +$ sudo make install app=1 ``` -Requires **perl >= 5.10** with `Test::Command`. The tests are non-interactive and -work without X, so they can safely be run even on a headless buildserver. +**For package maintainers and users who do not want feh to install its +icons into /usr/share:** +```bash +$ make +$ sudo make install +``` + +**Explanation:** feh ships some icons and an X11 desktop entry, which allow it to +be used from file managers, desktop menus and similar. However, installing +icons to /usr/local/share/... does not seem to work reliably. +Because of this, when using "make install app=1", feh will install its icons +to /usr/share/..., even though they technically belong into /usr/local. +[ZSH completion for +feh](https://git.finalrewind.org/zsh/plain/etc/completions/_feh) is also +available. -Testing (X) ------------ +## Testing (non-X11) -Requires - * import (usually supplied by imagemagick) - * perl >= 5.10 with GD, Test::More and X11::GUITest - * twm - * Xephyr +The non-X11 parts of feh can be automatically tested by running ```bash -$ make test-x11 +$ make test ``` - -**_Be aware that this is quite experimental, so far the X-tests have only been -run on one machine. So they may or may not work for you._** +This requires **perl >= 5.10** and the perl module `Test::Command`. Tests are +non-interactive and do not require a running X11, so they can safely be run on +a headless buildserver. + +## Contributing + +Bugfixes are always welcome, just open a pull request :) + +Before proposing a new feature, please consider the scope of feh: It is an +image viewer and cataloguer, not an image editor or similar. Also, its option +list is already pretty long. Please discuss your ideas in a feature request +before opening a pull request in this case. Also, keep in mind that feh is +developed as a hobby project and that there is absolutely no obligation for +anyone to implement requested features or review merge requests. + +Please keep in mind that feh's options, key bindings and format specifiers are +documented in two different places: The manual (man/feh.pre) and the help text +(src/help.raw). Although the help is not compiled in by default, it should be +kept up-to-date. On space-constrained embedded systems, it may be more useful +than the (significantly larger) man page. |