doc: add doc for the Chromium backend

This commit is contained in:
CismonX 2025-01-08 11:58:15 +08:00
parent 1602853772
commit 9960d67465
No known key found for this signature in database
GPG key ID: 3094873E29A482FB

View file

@ -876,6 +876,86 @@ on the bookmark storage before mounting with this option.
@node Chromium @node Chromium
@section Chromium Backend @section Chromium Backend
The Chromium backend provides access to the bookmark data of the web browser
@uref{https://www.chromium.org/Home/, Chromium} and its derivatives,
notably @uref{https://github.com/ungoogled-software/ungoogled-chromium,
ungoogled-chromium}.
Chromium bookmarks are stored in a text file (in JSON format)
under the profile directory:
@example
~/.config/chromium/@var{$@{profile_name@}}/Bookmarks
@end example
When mounting the filesystem, this pathname shall be passed as the @var{src}
argument (@pxref{mount.bookmarkfs}).
Actual path for the profile directories may differ across distributions.
Backend-specific options:
@table @option
@item filename=title|guid
Whether to use the bookmark title or GUID as the bookmark file name.
Defaults to ``title''.
A bookmark GUID is a hex-encoded (``8-4-4-4-12'', lowercase) 128-bit string
uniquely associated with a bookmark or bookmark folder.
When creating a new file:
@table @option
@item title
The GUID is randomly generated by the backend.
It is guaranteed to be a valid version 4 UUID as specified by
@uref{https://datatracker.ietf.org/doc/html/rfc4122, RFC 4122}.
@item guid
The filename must be a valid GUID, and must not duplicate with other files
on the same filesystem, otherwise @code{open()} fails with @code{EPERM}.
Also set the GUID string as the bookmark title.
@end table
@item watcher=native|fallback|none
The file watcher to use for the bookmark storage.
Defaults to ``native'' when the filesystem is mounted read-only,
``none'' otherwise.
@table @option
@item native
Watch for file changes using platform-specific features.
On Linux, @linuxmanpage{fanotify, 7} is used.
Requires kernel version 5.13 or later for unprivileged users.
@linuxmanpage{inotify, 7} does not have this limitation, however,
it is incompatible with our sandboxing design.
On FreeBSD, @freebsdmanpage{kevent, 2} with @code{EVFILT_VNODE} is used.
@item fallback
Watch for file changes by checking @code{st_ino} and @code{st_mtim} attributes
with @code{fstatat()} periodically.
Less efficient than ``native'' implementations, but should work on any
POSIX-compatible system.
@item none
Do not watch for file changes.
With @option{watcher=none}, changes on the bookmark storage are not visible
to the filesystem.
@end table
@end table
This backend does not scale well with large bookmark storage,
since it keeps everything in memory, and has to parse the entire JSON file
whenever a reload is required.
Another limitation is the lack of tags (@pxref{Tags}) and keywords
(@pxref{Keywords}) support.
Chromium does not have such concepts.
@node Backend API @node Backend API
@section Backend API @section Backend API