Krolyxon
Commit d0ec871

Branches

Refs →

nsxivREADME.md

235 lines · 8.3 KB · Markdown

Raw Blame History Download
1[![nsxiv](https://codeberg.org/nsxiv/pages/raw/branch/master/img/logo.png)](https://codeberg.org/nsxiv/nsxiv)
2
3[![CodeBerg](https://img.shields.io/badge/Hosted_at-Codeberg-%232185D0?style=flat-square&logo=CodeBerg)](https://codeberg.org/nsxiv/nsxiv)
4[![tags](https://img.shields.io/github/v/tag/nsxiv/nsxiv?style=flat-square)](https://codeberg.org/nsxiv/nsxiv/tags)
5[![license](https://img.shields.io/badge/license-GPL--2.0-lightgreen?style=flat-square)](https://codeberg.org/nsxiv/nsxiv/src/branch/master/LICENSE)
6[![loc](https://img.shields.io/tokei/lines/github/nsxiv/nsxiv?color=red&style=flat-square)](https://codeberg.org/nsxiv/nsxiv)
7
8**Neo (or New or Not) Simple (or Small or Suckless) X Image Viewer**
9--------------------------------------------------------------------
10
11nsxiv is a fork of the now-unmaintained [sxiv](https://github.com/xyb3rt/sxiv)
12with the purpose of being a (mostly) drop-in replacement for sxiv, maintaining its
13interface and adding simple, sensible features. nsxiv is free software licensed
14under GPLv2 and aims to be easy to modify and customize.
15
16Please file a bug report if something does not work as documented or expected on
17[Codeberg] after making sure you are using the latest release. Contributions
18are welcome, see [CONTRIBUTING] to get started.
19
20[Codeberg]: https://codeberg.org/nsxiv/nsxiv/issues/new
21[CONTRIBUTING]: etc/CONTRIBUTING.md#contribution-guideline
22
23
24Features
25--------
26
27* Basic image operations like zooming, panning, rotating
28* Basic support for animated/multi-frame images
29* Thumbnail mode: grid of selectable previews of all images
30* Ability to cache thumbnails for fast re-loading
31* Automatically refreshing modified images
32* Customizable keyboard and mouse mappings via `config.h`
33* Scriptability via `key-handler`
34* Displaying image information in status bar via `image-info` & `thumb-info`
35* Customizable window title via `win-title`
36
37
38Screenshots
39-----------
40
41**Image mode with default colors:**
42
43![Image](https://codeberg.org/nsxiv/pages/raw/branch/master/img/image.png "Image mode")
44
45**Thumbnail mode with custom colors:**
46
47![Thumb](https://codeberg.org/nsxiv/pages/raw/branch/master/img/thumb.png "Thumb mode")
48
49
50Installing via package manager
51------------------------------
52
53<a href="https://repology.org/project/nsxiv/versions">
54 <img align="right" width="192" src="https://repology.org/badge/vertical-allrepos/nsxiv.svg">
55</a>
56
57nsxiv is available on the following distributions/repositories. If you don't see
58your distro listed here, either contact your distro's package maintainer or
59consider packaging it yourself and adding it to the respective community repo.
60
61Repos not tracked by repology:
62
63* Fedora: Enable the copr repo via `dnf copr enable mamg22/nsxiv`.
64
65
66Dependencies
67------------
68
69nsxiv requires the following software to be installed:
70
71 * Imlib2
72 * X11
73
74The following dependencies are optional.
75
76 * `inotify`<sup>\*</sup>: Used for auto-reloading images on change.
77 Disabled via `HAVE_INOTIFY=0`.
78 * `libXft`, `freetype2`, `fontconfig`: Used for the status bar.
79 Disabled via `HAVE_LIBFONTS=0`.
80 * `libexif`: Used for auto-orientation and exif thumbnails.
81 Disable via `HAVE_LIBEXIF=0`.
82
83The following dependencies are only used if your imlib2 version is lower than
84v1.8.0. If your imlib2 version is v1.8.0 (or above) then the following
85dependencies are unused and won't be built (even if you enable it explicitly).
86
87 * `giflib`: Used for animated gif playback. Disabled via `HAVE_LIBGIF=0`.
88 * `libwebp`: Used for animated webp playback.
89 (***NOTE***: animated webp also requires Imlib2 v1.7.5 or above)
90 Disabled via `HAVE_LIBWEBP=0`.
91
92Please make sure to install the corresponding development packages in case that
93you want to build nsxiv on a distribution with separate runtime and development
94packages (e.g. \*-dev on Debian).
95
96\* [inotify][] is a Linux-specific API for monitoring filesystem changes.
97 It's not natively available on `*BSD` systems but can be enabed via installing
98 and linking against [libinotify-kqueue][].
99
100[inotify]: https://www.man7.org/linux/man-pages/man7/inotify.7.html
101[libinotify-kqueue]: https://github.com/libinotify-kqueue/libinotify-kqueue
102
103
104Building
105--------
106
107nsxiv is built using the commands:
108
109 $ make
110
111You can pass `HAVE_X=0` to `make` to disable an optional dependency.
112For example:
113
114 $ make HAVE_LIBEXIF=0
115
116will disable `libexif` support. Alternatively they can be disabled via editing
117`config.mk`. `OPT_DEP_DEFAULT=0` can be used to disable all optional
118dependencies.
119
120Installing nsxiv:
121
122 # make install
123
124Installing desktop entry:
125
126 # make install-desktop
127
128Installing icons:
129
130 # make install-icon
131
132Installing all of the above:
133
134 # make install-all
135
136Please note, that these requires root privileges.
137By default, nsxiv is installed using the prefix `/usr/local`, so the full path
138of the executable will be `/usr/local/bin/nsxiv`, the `.desktop` entry will be
139`/usr/local/share/applications/nsxiv.desktop` and the icon path will be
140`/usr/local/share/icons/hicolor/{size}/apps/nsxiv.png`.
141
142You can install nsxiv into a directory of your choice by changing this command to:
143
144 $ make PREFIX="/your/dir" install
145
146Example scripts are installed using `EGPREFIX` which defaults to
147`/usr/local/share/doc/nsxiv/examples`. You can change `EGPREFIX` the same way
148you can change `PREFIX` shown above.
149
150The build-time specific settings of nsxiv can be found in the file *config.h*.
151Please check and change them, so that they fit your needs.
152If the file *config.h* does not already exist, then you have to create it with
153the following command:
154
155 $ make config.h
156
157
158Usage
159-----
160
161Refer to the man-page for the documentation:
162
163 $ man nsxiv
164
165You may also view the man-page [online](https://nsxiv.codeberg.page/man/).
166However, note that the online man-page might not accurately represent your local
167copy.
168
169
170F.A.Q.
171------
172
173* Can I open remote urls with nsxiv? <br>
174Yes, see [nsxiv-url](https://codeberg.org/nsxiv/nsxiv-extra/src/branch/master/scripts/nsxiv-url)
175
176* Can I open all the images in a directory? <br>
177Yes, see [nsxiv-rifle](https://codeberg.org/nsxiv/nsxiv-extra/src/branch/master/scripts/nsxiv-rifle)
178
179* Can I set default arguments for nsxiv? <br>
180Yes, see [nsxiv-env](https://codeberg.org/nsxiv/nsxiv-extra/src/branch/master/scripts/nsxiv-env)
181
182* Can I pipe images into nsxiv? <br>
183Yes, see [nsxiv-pipe](https://codeberg.org/nsxiv/nsxiv-extra/src/branch/master/scripts/nsxiv-pipe)
184
185You may also wish to see the [known issues](https://codeberg.org/nsxiv/nsxiv/issues/242).
186
187
188Customization
189-------------
190
191The main method of customizing nsxiv is by setting values for the variables in *config.h*,
192or by using Xresources as explained in the manual. If these options are not sufficient,
193you may implement your own features by following
194[this guide](https://codeberg.org/nsxiv/nsxiv-extra/src/branch/master/CUSTOMIZATION.md).
195
196Due to our limited [project scope](etc/CONTRIBUTING.md#project-scope), certain features or
197customization cannot be merged into nsxiv mainline. Following the spirit of suckless
198software, we host the [nsxiv-extra](https://codeberg.org/nsxiv/nsxiv-extra) repo where users
199are free to submit whatever patches or scripts they wish.
200
201If you think your custom features can be beneficial for the general user base and is within
202our project scope, please submit it as a pull request on this repository, then we *may*
203merge it to mainline.
204
205Description on how to use or submit patches can be found on
206nsxiv-extra's [README](https://codeberg.org/nsxiv/nsxiv-extra).
207
208
209Download
210--------
211
212You can [browse](https://codeberg.org/nsxiv/nsxiv) the source code repository
213on CodeBerg or get a copy using git with the following command:
214
215 $ git clone https://codeberg.org/nsxiv/nsxiv.git
216
217You can view the changelog [here](etc/CHANGELOG.md)
218
219
220Similar projects
221----------------
222
223If nsxiv isn't able to fit your needs, check out the image viewer section of
224**[suckless rocks](https://suckless.org/rocks)** to find other minimal image
225viewers to try out.
226
227Below are a couple other lesser known projects not listed in suckless rocks.
228
229* [MAGE](https://codeberg.org/explosion-mental/mage):
230 A smaller/more-suckless version of sxiv.
231* [div](https://codeberg.org/TAAPArthur/div):
232 Minimal and extensive, aimed at C devs willing to build their own features.
233* [mpv-image-viewer](https://github.com/occivink/mpv-image-viewer):
234 Lua script to turn mpv into an image viewer. Supports thumbnails via
235 [mpv-gallery-view](https://github.com/occivink/mpv-gallery-view).