[wiki/libmutton] Add developer guide (for third-party implementations)

2026-08-27 20:36:29 -04:00 · 2024-07-07 23:52:33 -04:00
parent 40c5db5940
commit 08af2a3761
2 changed files with 20 additions and 1 deletions
@@ -0,0 +1,19 @@
+## Developer Guide (for third-party libmutton implementations)
+**Important Notice**: libmutton is in early development and is currently a moving target to develop off of. Feel free to jump in early, but greater change stability will be met with release v1.0.0. Check [here](https://github.com/rwinkhart/MUTN/blob/main/wiki/libmutton/breaking.md) for planned breaking changes.
+
+libmutton was designed to be usable as a library for building other compatible password managers off of. [MUTN](https://github.com/rwinkhart/MUTN) is the official reference CLI password manager, however libmutton can be implemented in many other unique ways.
+
+All functionality in the `backend` and `sync` packages are designed to be used in other implementations.
+
+## Build Tags
+Custom build tags can be (and sometimes must be) used to achieve desired results.
+
+These are as follows:
+- `returnOnExit`: If making an interactive interface (GUI/TUI/interactive CLI), you probably need to use this build tag. Without it, your entire program will exit after any given operation is completed. This behavior is only desired for non-interactive CLI implementations, such as MUTN. Currently, errors will result in the program exiting **even with this build tag**. This may be changed in the future (under evaluation).
+- `wsl`: Allows creating a Linux binary that can interact with the Windows clipboard (for WSL)
+- `termux`: Allows creating a Linux binary that can interact with the Termux clipboard (for Android)
+
+## Required Arguments
+libmutton-based password managers should accept at least one specific required argument, as well as another recommended one:
+- `clipclear`: This argument is required for correct functionality. In order to clear the clipboard on a timer, libmutton-based password managers call another instance of their executable with the `clipclear` argument (e.g. `mutn clipclear`) with the intended clipboard contents provided via STDIN. If after 30 seconds the clipboard contents have not changed, they are cleared. Please accept a `clipclear` argument that is processed before the launch of any interactive interface. All this argument needs to do is call `backend.ClipClearArgument()`.
+- `init`: This argument is optional, but recommended for CLI interfaces. Some error messages request the user to use the `init` argument to fix configuration issues. If the argument does not exist, this may confuse the user.
@@ -5,4 +5,4 @@ libmutton-based password managers *currently* use GnuPG encryption and an entry
 ### sshyp
 sshyp, though also `pass`-compatible, makes some changes to the entry format that take effect once the entry has been imported. The changes made by sshyp are not compatible with libmutton, and as such sshyp entries must be converted before they can be used. A script for doing that has been created and is available in the sshyp extension store. Simply run `sshyp tweak`, go to the "extension management" menu, and download the "export-to-libmutton" extension. After doing this, the `sshyp export` command can be used to export entries in libmutton format.
 ### Other
-The formats for many other password managers can be converted to the `pass` format with community scripts. Some of these scripts are listed [here](https://www.passwordstore.org/#migration). Once converted, they can be dropped into `~/.local/share/libmutton`.
+The formats for many other password managers can be converted to the `pass` format with community scripts. Some of these scripts are listed [here](https://www.passwordstore.org/#migration). Once converted, entries can be dropped into `~/.local/share/libmutton`.