86 lines
3.0 KiB
Plaintext
86 lines
3.0 KiB
Plaintext
hex
|
|
===
|
|
|
|
'hex' is yet another hex viewer. It automatically interprets fields within
|
|
files using a set of Lua scripts, colorizing them and showing descriptions on
|
|
the side. It also runs equally well in the terminal, or as an X11 client.
|
|
|
|
At the moment there aren't that many features and we only have a few decoders.
|
|
|
|
image::hex.png[align="center"]
|
|
|
|
Packages
|
|
--------
|
|
Regular releases are sporadic. git master should be stable enough.
|
|
You can get a package with the latest development version using Arch Linux's
|
|
https://aur.archlinux.org/packages/hex-git[AUR],
|
|
or as a https://git.janouch.name/p/nixexprs[Nix derivation].
|
|
|
|
Documentation
|
|
-------------
|
|
See the link:hex.adoc[man page] for information about usage.
|
|
The rest of this README will concern itself with externalities.
|
|
|
|
Building and Running
|
|
--------------------
|
|
Build-only dependencies: CMake, pkg-config, awk, liberty (included),
|
|
termo (included), asciidoctor or asciidoc (recommended but optional),
|
|
rsvg-convert (X11) +
|
|
Runtime dependencies: ncursesw, libunistring, Lua >= 5.3 (for highlighting) +
|
|
Optional runtime dependencies: x11 + xft + libpng (X11)
|
|
|
|
$ git clone --recursive https://git.janouch.name/p/hex.git
|
|
$ mkdir hex/build
|
|
$ cd hex/build
|
|
$ cmake .. -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Debug
|
|
$ make
|
|
|
|
To install the application, you can do either the usual:
|
|
|
|
# make install
|
|
|
|
Or you can try telling CMake to make a package for you. For Debian it is:
|
|
|
|
$ cpack -G DEB
|
|
# dpkg -i hex-*.deb
|
|
|
|
Having the program installed, optionally create a configuration file and run it
|
|
on a file of your choice.
|
|
|
|
Terminal caveats
|
|
----------------
|
|
Terminals are somewhat tricky to get consistent results on, so be aware of the
|
|
following:
|
|
|
|
- Xterm needs `XTerm*metaSendsEscape: true` for the default bindings to work
|
|
- urxvt's 'vtwheel' plugin sabotages scrolling
|
|
|
|
Performance
|
|
-----------
|
|
While the Lua API has been made considerably easy to write new decoders with,
|
|
the design is far from efficient as we make tons of new formatted strings.
|
|
Since we need Lua 5.3 features (64-bit integers), LuaJIT can't help us here.
|
|
|
|
Similar software
|
|
----------------
|
|
* https://ide.kaitai.io/ and https://codisec.com/veles/ are essentially what
|
|
this project wanted to be but the description language is purely declarative
|
|
* https://github.com/wader/fq goes a step above, allowing transformations
|
|
of identified data
|
|
* https://hachoir.readthedocs.io/en/latest/ seems to be strictly hierarchical,
|
|
which may not work for file formats like ELF
|
|
* https://github.com/ruslashev/elfcat is a more interactive viewer for ELF
|
|
|
|
Contributing and Support
|
|
------------------------
|
|
Use https://git.janouch.name/p/hex to report any bugs, request features,
|
|
or submit pull requests. `git send-email` is tolerated. If you want to discuss
|
|
the project, feel free to join me at ircs://irc.janouch.name, channel #dev.
|
|
|
|
Bitcoin donations are accepted at: 12r5uEWEgcHC46xd64tt3hHt9EUvYYDHe9
|
|
|
|
License
|
|
-------
|
|
This software is released under the terms of the 0BSD license, the text of which
|
|
is included within the package along with the list of authors.
|