| 1 | Dependencies |
| 2 | ------------ |
| 3 | |
| 4 | nsxiv requires the following software to be installed: |
| 5 | |
| 6 | * Imlib2 |
| 7 | * X11 |
| 8 | |
| 9 | The following dependencies are optional. |
| 10 | |
| 11 | * `inotify`<sup>\*</sup>: Used for auto-reloading images on change. |
| 12 | Disabled via `HAVE_INOTIFY=0`. |
| 13 | * `libXft`, `freetype2`, `fontconfig`: Used for the status bar. |
| 14 | Disabled via `HAVE_LIBFONTS=0`. |
| 15 | * `giflib`: Used for animated gif playback. |
| 16 | Disabled via `HAVE_LIBGIF=0`. |
| 17 | * `libexif`: Used for auto-orientation and exif thumbnails. |
| 18 | Disable via `HAVE_LIBEXIF=0`. |
| 19 | * `libwebp`: Used for animated webp playback. |
| 20 | (***NOTE***: animated webp also requires Imlib2 v1.7.5 or above) |
| 21 | Disabled via `HAVE_LIBWEBP=0`. |
| 22 | |
| 23 | Please make sure to install the corresponding development packages in case that |
| 24 | you want to build nsxiv on a distribution with separate runtime and development |
| 25 | packages (e.g. \*-dev on Debian). |
| 26 | |
| 27 | \* [inotify][] is a Linux-specific API for monitoring filesystem changes. |
| 28 | It's not natively available on `*BSD` systems but can be enabed via installing |
| 29 | and linking against [libinotify-kqueue][]. |
| 30 | |
| 31 | [inotify]: https://www.man7.org/linux/man-pages/man7/inotify.7.html |
| 32 | [libinotify-kqueue]: https://github.com/libinotify-kqueue/libinotify-kqueue |
| 33 | |
| 34 | |
| 35 | Building |
| 36 | -------- |
| 37 | |
| 38 | nsxiv is built using the commands: |
| 39 | |
| 40 | $ make |
| 41 | |
| 42 | You can pass `HAVE_X=0` to `make` to disable an optional dependency. |
| 43 | For example: |
| 44 | |
| 45 | $ make HAVE_LIBEXIF=0 |
| 46 | |
| 47 | will disable `libexif` support. Alternatively they can be disabled via editing |
| 48 | `config.mk`. `OPT_DEP_DEFAULT=0` can be used to disable all optional |
| 49 | dependencies. |
| 50 | |
| 51 | Installing nsxiv: |
| 52 | |
| 53 | # make install |
| 54 | |
| 55 | Installing desktop entry: |
| 56 | |
| 57 | # make install-desktop |
| 58 | |
| 59 | Installing icons: |
| 60 | |
| 61 | # make install-icon |
| 62 | |
| 63 | Installing all of the above: |
| 64 | |
| 65 | # make install-all |
| 66 | |
| 67 | Please note, that these requires root privileges. |
| 68 | By default, nsxiv is installed using the prefix `/usr/local`, so the full path |
| 69 | of the executable will be `/usr/local/bin/nsxiv`, the `.desktop` entry will be |
| 70 | `/usr/local/share/applications/nsxiv.desktop` and the icon path will be |
| 71 | `/usr/local/share/icons/hicolor/{size}/apps/nsxiv.png`. |
| 72 | |
| 73 | You can install nsxiv into a directory of your choice by changing this command to: |
| 74 | |
| 75 | $ make PREFIX="/your/dir" install |
| 76 | |
| 77 | Example scripts are installed using `EGPREFIX` which defaults to |
| 78 | `/usr/local/share/doc/nsxiv/examples`. You can change `EGPREFIX` the same way |
| 79 | you can change `PREFIX` shown above. |
| 80 | |
| 81 | The build-time specific settings of nsxiv can be found in the file *config.h*. |
| 82 | Please check and change them, so that they fit your needs. |
| 83 | If the file *config.h* does not already exist, then you have to create it with |
| 84 | the following command: |
| 85 | |
| 86 | $ make config.h |
| 87 | |
| 88 | |
| 89 | Usage |
| 90 | ----- |
| 91 | |
| 92 | Refer to the man-page for the documentation: |
| 93 | |
| 94 | $ man nsxiv |
| 95 | |
| 96 | You may also view the man-page [online](https://nsxiv.codeberg.page/man/). |
| 97 | However, note that the online man-page might not accurately represent your local |
| 98 | copy. |
| 99 | |
| 100 | |
| 101 | F.A.Q. |
| 102 | ------ |
| 103 | |
| 104 | * Can I open remote urls with nsxiv? <br> |
| 105 | Yes, see [nsxiv-url](https://codeberg.org/nsxiv/nsxiv-extra/src/branch/master/scripts/nsxiv-url) |
| 106 | |
| 107 | * Can I open all the images in a directory? <br> |
| 108 | Yes, see [nsxiv-rifle](https://codeberg.org/nsxiv/nsxiv-extra/src/branch/master/scripts/nsxiv-rifle) |
| 109 | |
| 110 | * Can I set default arguments for nsxiv? <br> |
| 111 | Yes, see [nsxiv-env](https://codeberg.org/nsxiv/nsxiv-extra/src/branch/master/scripts/nsxiv-env) |
| 112 | |
| 113 | * Can I pipe images into nsxiv? <br> |
| 114 | Yes, see [nsxiv-pipe](https://codeberg.org/nsxiv/nsxiv-extra/src/branch/master/scripts/nsxiv-pipe) |
| 115 | |
| 116 | You may also wish to see the [known issues](https://codeberg.org/nsxiv/nsxiv/issues/242). |
| 117 | |
| 118 | |
| 119 | Customization |
| 120 | ------------- |
| 121 | |
| 122 | The main method of customizing nsxiv is by setting values for the variables in *config.h*, |
| 123 | or by using Xresources as explained in the manual. If these options are not sufficient, |
| 124 | you may implement your own features by following |
| 125 | [this guide](https://codeberg.org/nsxiv/nsxiv-extra/src/branch/master/CUSTOMIZATION.md). |
| 126 | |
| 127 | Due to our limited [project scope](etc/CONTRIBUTING.md#project-scope), certain features or |
| 128 | customization cannot be merged into nsxiv mainline. Following the spirit of suckless |
| 129 | software, we host the [nsxiv-extra](https://codeberg.org/nsxiv/nsxiv-extra) repo where users |
| 130 | are free to submit whatever patches or scripts they wish. |
| 131 | |
| 132 | If you think your custom features can be beneficial for the general user base and is within |
| 133 | our project scope, please submit it as a pull request on this repository, then we *may* |
| 134 | merge it to mainline. |
| 135 | |
| 136 | Description on how to use or submit patches can be found on |
| 137 | nsxiv-extra's [README](https://codeberg.org/nsxiv/nsxiv-extra). |