be69828675
This command line option runs a refresh without opening a window and closes down the application after the process is done, but only if no window is active at that time. Distros that ship Bazaar could trigger this command at first boot so users don't have to wait like 10 seconds until everything is synced up.
839 lines
29 KiB
Markdown
839 lines
29 KiB
Markdown
# Bazaar Overview
|
|
|
|
These docs are intended for distributors of Bazaar to learn how to configure the
|
|
application.
|
|
|
|
## Features
|
|
Here is a short list of some of the things Bazaar can do, beyond the basics of
|
|
managing software through the GUI:
|
|
|
|
* Queue an arbitrary number of transactions (a catch-all term for installations,
|
|
updates, and removals) during which you may close all windows or continue to
|
|
append new transactions freely
|
|
|
|
* Display a "Curated" page which you may extensively customize with YAML.
|
|
* This is a way to highlight applications which you believe might be of
|
|
interest.
|
|
* Curated configuration files are constantly monitored for filesystem events,
|
|
changes immediately reflected in the GUI
|
|
* Any number of curated configuration files; they will concatenate in the GUI
|
|
in the order they were provided
|
|
|
|
* Access data from [Flathub](https://flathub.org/), such as the latest or most
|
|
popular applications, and allow users to sign in to Flathub to manage
|
|
bookmarked applications
|
|
|
|
* Run in the background and respond to desktop search queries with application
|
|
info, using the same search routine as in-application
|
|
- GNOME will work out of the box, as Bazaar implements the
|
|
`org.gnome.Shell.SearchProvider2` dbus interface
|
|
- KDE Plasma will require a [krunner
|
|
plugin](https://github.com/ublue-os/krunner-bazaar)
|
|
|
|
* Hide applications you do not want users to see with blocklists, which is
|
|
useful for discouraging the use of certain packages which you deem to be
|
|
broken.
|
|
|
|
* Manage an arbitrary amount of windows and keep them synchronized
|
|
|
|
* Communicate with, and invoke operations on, the main daemon through the
|
|
command line
|
|
|
|
## CLI Usage
|
|
|
|
You can start the bazaar daemon like this:
|
|
|
|
```
|
|
bazaar-daemon [ARGS] [PACKAGE PATH/URI]
|
|
```
|
|
|
|
`[PACKAGE PATH/URI]` could be a `.flatpakref` file. flatpak+https and regular
|
|
https is supported.
|
|
|
|
To avoid spawning an initial window, use:
|
|
|
|
```
|
|
bazaar-daemon --no-window
|
|
```
|
|
|
|
To refresh remotes in the background without ever opening a window, and quit
|
|
automatically once the refresh finishes, use:
|
|
|
|
```
|
|
bazaar-daemon --no-window-refresh
|
|
```
|
|
Running this automatically in the background after the first boot of the OS
|
|
makes it so the user doesn't have to wait for the initial cache/remote sync
|
|
when they open Bazaar for the first time, saving around 10s of waiting.
|
|
|
|
## Comptime Configuration
|
|
|
|
The only compile time meson option you should concern yourself with for
|
|
production is `hardcoded_main_config_path`. This embeds a path to the main
|
|
configuration file into Bazaar. If this is not defined at compile time, Bazaar
|
|
will never attempt to read a main config. See the next section of this document
|
|
to see an example config file.
|
|
|
|
## Environment Variables
|
|
|
|
Bazaar reads the following environment variables, which may be of interest:
|
|
|
|
* `BAZAAR_DESKTOP_SEARCH_PROVIDER_ICON_SIZE`: may be read as an unsigned integer
|
|
from 1 to 256 to specify the square pixel size of icons sent to the desktop
|
|
search provider. This should be configured to be a higher value than its default
|
|
value of 24x24 when on KDE, as krunner paints result icons as much larger than
|
|
gnome-shell does. This way, the images will not appear blurry.
|
|
|
|
* `BAZAAR_N_DOWNLOAD_WORKERS`: may be read as an unsigned integer greater than 0
|
|
to specify the number of image download worker subprocesses that should be
|
|
spawned and managed by Bazaar to fetch screenshots, icons, and other images. By
|
|
default, Bazaar spawns 8 download workers. Download workers are always killed
|
|
when Bazaar has no active windows and ensured when Bazaar returns to having 1 or
|
|
more windows.
|
|
|
|
## Main Configuration
|
|
|
|
This is the primary YAML configuration file for bazaar, as designated by the
|
|
`hardcoded_main_config_path` meson option. Here, you will point bazaar to where
|
|
your other configs are located. You can also define hooks in this file. See the
|
|
"Hooks" section of this document for an overview of the hooks system and an
|
|
example of integration into the main config.
|
|
|
|
### Example
|
|
|
|
```yaml
|
|
yaml-blocklist-paths:
|
|
- /path/to/yaml/blocklist.yaml
|
|
- /path/to/another/yaml/blocklist.yaml
|
|
# Flatpak path with host-etc permission
|
|
- /run/host/etc/bazaar/blocklist.yaml
|
|
txt-blocklist-paths:
|
|
- /path/to/txt/blocklist.txt
|
|
- /path/to/another/txt/blocklist.txt
|
|
# Flatpak path with host-etc permission
|
|
- /run/host/etc/bazaar/blocklist.txt
|
|
curated-config-paths:
|
|
- /path/to/yaml/file.yaml
|
|
- /path/to/another/yaml/file.yaml
|
|
# Flatpak path with host-etc permission
|
|
- /run/host/etc/bazaar/curated.yaml
|
|
# Make the app start on the curated page instead of the explore page, try to only use if you have an interesting news section
|
|
start-on-curated: true
|
|
# Hide the auto update options in the preferences dialog, useful when you want to avoid confusion if your distro handles auto-updates of Flatpaks already.
|
|
hide-auto-update-options: true
|
|
```
|
|
|
|
### EOL Overrides
|
|
|
|
In this file, you can also specify a list of apps for which to hide EOL warnings
|
|
and therefore prevent users from being deterred from installing them:
|
|
|
|
```yaml
|
|
override-eol-markings:
|
|
- com.obsproject.Studio
|
|
- net.lutris.Lutris
|
|
```
|
|
|
|
(At the time of writing, the projects listed above rely on EOL runtimes but are
|
|
otherwise widely used)
|
|
|
|
## Blocklists
|
|
|
|
Blocklists are a way to ensure that users will never interact with a certain
|
|
application inside Bazaar by searching or browsing, either on the Flathub page
|
|
or via search.
|
|
|
|
Blocked applications which are already installed still appear in
|
|
the library or when there are updates available for them and via the system's
|
|
flatpak configuration. Under no circumstance does Bazaar touch the underlying
|
|
flatpak configuration in order to block or allow apps. The `flatpak` command
|
|
line tool is unaffected.
|
|
|
|
### Blocklist Types
|
|
|
|
There are two kinds of blocklists supported by Bazaar:
|
|
|
|
#### YAML Blocklists
|
|
|
|
For those who are learn more effectively by seeing an example:
|
|
|
|
```yaml
|
|
blocklists:
|
|
- priority: 0
|
|
block-regex:
|
|
# block all ids matching this regex unconditionally
|
|
- com\.place\..*
|
|
- priority: -1 # lower number = more priority
|
|
conditions:
|
|
- match-locale:
|
|
# only apply this rule if we have the Arabic locale
|
|
regex: ar
|
|
allow:
|
|
- com.place.App3
|
|
- com.place.App5
|
|
allow-regex:
|
|
- com\.place\..*\.ar
|
|
- priority: -1
|
|
conditions:
|
|
- match-locale:
|
|
regex: en.*
|
|
# invert the result of this condition; so all locales which don't match
|
|
# the regex
|
|
post-process: invert
|
|
- match-envvar:
|
|
var: PATH
|
|
regex: .*/usr/local/bin.*
|
|
block:
|
|
- com.other.App1
|
|
allow:
|
|
- com.place.App1
|
|
- com.place.App2
|
|
```
|
|
|
|
YAML blocklists files are comprised of a list of sub "blocklists," which to
|
|
Bazaar means a **list of appids to block or allow**. These are optionally
|
|
**applied based on a list of provided conditions** and **composed with other
|
|
blocklists in the list based on a priority**.
|
|
|
|
Each blocklist may contain these fields:
|
|
|
|
* `priority`: a number which tells Bazaar how to layer this blocklist with the
|
|
others, or how "important" this blocklist is. **A lower number means more
|
|
priority**.
|
|
|
|
* `conditions`: a list of conditions to apply. Two condition types exist at the
|
|
moment: `match-locale` and `match-envvar`. TODO: describe these
|
|
|
|
* `block`: a list of appids to block. These are matched without regex.
|
|
|
|
* `block-regex`: a list of appids to block. These allow regex syntax for special matching.
|
|
|
|
* `allow`: a list of appids to allow. These are matched without regex.
|
|
|
|
* `allow-regex`: a list of appids to allow. These allow regex syntax for special matching.
|
|
|
|
#### Basic Newline Separated TXT Blocklists
|
|
|
|
This type of blocklist is what Bazaar originally supported. They still function,
|
|
but it is encouraged to use YAML blocklists if any sort of pattern matching or
|
|
conditional inclusion is required.
|
|
|
|
```
|
|
# comments are supported
|
|
com.jetbrains.CLion
|
|
com.valvesoftware.Steam
|
|
|
|
# empty lines are allowed
|
|
|
|
io.neovim.nvim
|
|
net.lutris.Lutris
|
|
```
|
|
|
|
Warning: **Incorrect Buzzer** TXT blocklists do not support regular expressions.
|
|
This matches the literal text provided
|
|
|
|
```
|
|
com\.place\..*
|
|
```
|
|
|
|
### Blocklist FAQ
|
|
|
|
#### No Worky
|
|
|
|
Check that the path of the blocklist exists and that Bazaar can access it. This command is useful for debugging this:
|
|
|
|
```
|
|
flatpak run --command=bash io.github.kolunmi.Bazaar
|
|
```
|
|
|
|
The `/etc` of the host system accessed from a Flatpak requires the `host-etc` permission.
|
|
|
|
This means `/etc/bazaar/banner.png` turns into `/run/host/etc/bazaar/banner.png`.
|
|
|
|
#### I want to to block a list of applications all the time, and also another list only on desktop environment X:
|
|
|
|
Say you want to block Bazaar and Steam unconditionally and Kate and KWrite if
|
|
the desktop is Plasma. You can use an environment variable condition to check
|
|
the value of `XDG_CURRENT_DESKTOP`:
|
|
|
|
```yaml
|
|
blocklists:
|
|
- block:
|
|
- io.github.kolunmi.Bazaar
|
|
- com.valvesoftware.Steam
|
|
|
|
- block:
|
|
- org.kde.kate
|
|
- org.kde.kwrite
|
|
conditions:
|
|
- match-envvar:
|
|
var: XDG_CURRENT_DESKTOP
|
|
regex: KDE
|
|
```
|
|
|
|
Let's add another for GNOME:
|
|
```yaml
|
|
blocklists:
|
|
- block:
|
|
- io.github.kolunmi.Bazaar
|
|
- com.valvesoftware.Steam
|
|
|
|
- block:
|
|
- org.kde.kate
|
|
- org.kde.kwrite
|
|
conditions:
|
|
- match-envvar:
|
|
var: XDG_CURRENT_DESKTOP
|
|
regex: KDE
|
|
|
|
- block:
|
|
- org.gnome.eog
|
|
- org.gnome.Extensions
|
|
conditions:
|
|
- match-envvar:
|
|
var: XDG_CURRENT_DESKTOP
|
|
regex: GNOME
|
|
```
|
|
|
|
#### What about blocking an application by default, but allowing it if a condition resolves to true?
|
|
|
|
Taking from the previous example, let's allow Steam on KDE and GNOME, but block
|
|
it on other desktops. We'll need to give the DE-specific blocklists more
|
|
priority:
|
|
|
|
```yaml
|
|
blocklists:
|
|
- priority: 1
|
|
block:
|
|
- io.github.kolunmi.Bazaar
|
|
- com.valvesoftware.Steam
|
|
|
|
- block:
|
|
- org.kde.kate
|
|
- org.kde.kwrite
|
|
allow:
|
|
- com.valvesoftware.Steam
|
|
conditions:
|
|
- match-envvar:
|
|
var: XDG_CURRENT_DESKTOP
|
|
regex: KDE
|
|
|
|
- block:
|
|
- org.gnome.eog
|
|
- org.gnome.Extensions
|
|
allow:
|
|
- com.valvesoftware.Steam
|
|
conditions:
|
|
- match-envvar:
|
|
var: XDG_CURRENT_DESKTOP
|
|
regex: GNOME
|
|
```
|
|
|
|
You could also make a new blocklist matching both `KDE` and `GNOME`:
|
|
|
|
```yaml
|
|
blocklists:
|
|
- priority: 1
|
|
block:
|
|
- io.github.kolunmi.Bazaar
|
|
- com.valvesoftware.Steam
|
|
|
|
- block:
|
|
- org.kde.kate
|
|
- org.kde.kwrite
|
|
conditions:
|
|
- match-envvar:
|
|
var: XDG_CURRENT_DESKTOP
|
|
regex: KDE
|
|
|
|
- block:
|
|
- org.gnome.eog
|
|
- org.gnome.Extensions
|
|
conditions:
|
|
- match-envvar:
|
|
var: XDG_CURRENT_DESKTOP
|
|
regex: GNOME
|
|
|
|
- allow:
|
|
- com.valvesoftware.Steam
|
|
conditions:
|
|
- match-envvar:
|
|
var: XDG_CURRENT_DESKTOP
|
|
regex: KDE|GNOME
|
|
```
|
|
|
|
## Curated Section
|
|
|
|
If Bazaar is provided a non-zero amount of curated configs, an extra tab will
|
|
appear on the window's header bar called "Curated". This section is intended for
|
|
distributors to curate applications for users with a customizable interface.
|
|
Curated configs are YAML files. They are constantly monitored by Bazaar for
|
|
filesystem events, so when the config changes, Bazaar will automatically reload
|
|
the content.
|
|
|
|
Right now, curated configs are essentially composed of a vertical list of
|
|
elements which appear stacked on top of each other inside of a scrollable
|
|
viewport in the order they appear in the YAML. Each element has certain
|
|
properties you can customize.
|
|
|
|
Bazaar maps the appids you provide to the best matching "entry group" from the
|
|
table of applications it was able to pull from remote sources (Simply put, an
|
|
entry group in Bazaar is a collection of applications which share the same appid
|
|
but come from different sources or installations). The entry group has a
|
|
designated "ui entry" which was determined to have the most useful content
|
|
associated with it as it pertains to presenting things like icons, descriptions,
|
|
screenshots, etc to the user, usually from Flathub when available.
|
|
|
|
When the user selects an app, they are brought to a "full view" where they can
|
|
see a bunch of information stored inside or referenced by the ui entry and
|
|
choose to invoke transactions on the entry group, like installation or removal.
|
|
|
|
### Example
|
|
|
|
An example can be found in docs/example.yaml
|
|
|
|
### Integrate the curated section + blocklist with the official Flatpak for Administrators/Vendors
|
|
|
|
For more practical examples check out the configuration from [Bluefin](https://github.com/projectbluefin/common/tree/a868eba107b91c4eae60b6d1d6d2e2cdf05eb1c8/system_files/bluefin/etc/bazaar) and [Aurora](https://github.com/get-aurora-dev/common/tree/0d86028dd0d737d1d0eee08205c33fc91997f155/system_files/shared/etc/bazaar).
|
|
|
|
Bazaar by default looks for a config file in `/etc/bazaar` or `/run/host/etc/bazaar` inside the sandbox, this is [configured on build time](https://github.com/flathub/io.github.kolunmi.Bazaar/blob/709faccd8c4198c5fdabf20eb4a98db98a5aa1c6/io.github.kolunmi.Bazaar.yaml#L43-L46) This needs permission to `/etc` which can be granted with the `filesystem=host-etc` permission, the build on Flathub doesn't have this permission by default.
|
|
|
|
This is not super straightforward to setup currently as Flatpak doesn't support overriding permissions in `/etc` or `/usr` yet, so you have to resort to `systemd-tmpfiles` to create this permission override in `/var/lib/flatpak/overrides/io.github.kolunmi.Bazaar`.
|
|
|
|
Here is how they did it:
|
|
|
|
- [tmpfiles](https://github.com/get-aurora-dev/common/blob/0d86028dd0d737d1d0eee08205c33fc91997f155/system_files/shared/usr/lib/tmpfiles.d/bazaar-flatpak.conf)
|
|
|
|
- [actual permission override](https://github.com/get-aurora-dev/common/blob/0d86028dd0d737d1d0eee08205c33fc91997f155/system_files/shared/usr/share/ublue-os/flatpak-overrides/io.github.kolunmi.Bazaar), the filepath for this doesn't really matter, just a way for you to ship the symlink with tmpfiles
|
|
|
|
## Article markdown
|
|
|
|
Curated articles support standard markdown, rendered with GTK widgets (so its
|
|
not a webview).
|
|
|
|
**Supported:**
|
|
- Basic markdown
|
|
- Inline code
|
|
- Code blocks (with syntax highlighting if language is specified)
|
|
- Ordered and unordered lists
|
|
- Tables
|
|
- Horizontal rules
|
|
- Links
|
|
|
|
**Not supported**:
|
|
- Raw HTML
|
|
- Latex
|
|
- Other weird things
|
|
- Column alignment in tables
|
|
|
|
### Inline images & app tiles
|
|
|
|
Regular image syntax (``) renders a
|
|
normal image/screenshot.
|
|
|
|
Two special URI schemes can be used instead to render app tiles inline:
|
|
|
|
* `appstream://<appid>`: looks up a real app by its appid and renders like any
|
|
other app button.
|
|
* `bazaar-hook://?id=<id>&title=<title>&subtitle=<subtitle>&icon=<icon-uri>`:
|
|
renders a fake tile that is not backed by a real app. Clicking it runs an
|
|
`article-app` hook instead of opening a full app view.
|
|
|
|
You can mix multiple tiles of either kind into one row by comma-separating them
|
|
inside a single image tag:
|
|
|
|
```markdown
|
|
|
|
```
|
|
|
|
Every curated article already shows the title from the curated section at the
|
|
top, so please do not include it in the markdown itself.
|
|
|
|
## Hooks
|
|
|
|
Hooks are an advanced feature of Bazaar. In essence, they allow you to
|
|
programmatically react to events and define dialogs with which you can query
|
|
user input. Currently, these are the event signals you can subscribe to:
|
|
|
|
* `view-app`: run the hook when the user clicks on an app tile or otherwise
|
|
views an application in the main app page
|
|
|
|
* `article-app`: run the hook when the user clicks a `bazaar-hook://` tile
|
|
inside a curated article
|
|
|
|
* `before-transaction`: run the hook right as the user invokes a transaction
|
|
|
|
* `after-transaction`: run the hook after a transaction completes
|
|
|
|
Hooks are run like a signal emission. After an event occurs, hooks that are
|
|
found to be of the appropriate type are evaluated in an order of priority.
|
|
Higher priority hooks have the ability to stop the emission from propagating
|
|
further downwards. In the case of some events, like "before-transaction", a hook
|
|
can also hint to Bazaar some action to take, in this case whether the
|
|
transaction should be aborted.
|
|
|
|
A shell snippet which is defined by you is evaluated with `/bin/sh -c` multiple
|
|
times over the course of a hook's execution. An invocation of the shell snippet
|
|
is referred to as a "stage". Your shell snippet (which of course could just
|
|
invoke another script written in whatever language you prefer) will be provided
|
|
a number of environment variables which together will describe the current
|
|
stage. Your snippet must react accordingly by printing a response to stdout,
|
|
which Bazaar will read back.
|
|
|
|
This opens up a lot of possibilities for customization; here are a few examples:
|
|
|
|
* You would like a certain appid to be added to steam after the user installs
|
|
it, so you register a hook on "after-transaction" to query the user's
|
|
permission with a custom dialog. If they confirm, your script will go forward
|
|
with the task of setting up a steam shortcut.
|
|
|
|
* You would like to prevent users from installing a certain appid, as some other
|
|
method of installation, such as a system package, would provide a superior
|
|
experience. A blocklist could achieve this, but you don't like the idea of
|
|
hiding anything from the user. A hook subscribed to the "before-transaction"
|
|
event could issue a warning and ask for extra confirmation. If the user
|
|
decides to listen to the warning, you can signal to Bazaar that the
|
|
transaction should be aborted.
|
|
|
|
Here is an overview of the environment variables the shell snippet will receive:
|
|
|
|
* `BAZAAR_HOOK_INITIATED_UNIX_STAMP`: the unix timestamp in seconds at which
|
|
this hook was first invoked (the number of seconds that have elapsed since
|
|
1970-01-01 00:00:00 UTC)
|
|
|
|
* `BAZAAR_HOOK_INITIATED_UNIX_STAMP_USEC`: the unix timestamp in microseconds at
|
|
which this hook was first invoked (the number of microseconds that have
|
|
elapsed since 1970-01-01 00:00:00 UTC)
|
|
|
|
* `BAZAAR_HOOK_STAGE_IDX`: the number of stages this hook has run so far
|
|
|
|
* `BAZAAR_HOOK_ID`: the value of the "id" mapping
|
|
|
|
* `BAZAAR_HOOK_TYPE`: the value of the "when" mapping
|
|
|
|
* `BAZAAR_HOOK_WAS_ABORTED`: "true" if a dialog aborted the hook
|
|
|
|
* `BAZAAR_HOOK_DIALOG_ID`: if applicable, the id of the current dialog
|
|
|
|
* `BAZAAR_HOOK_DIALOG_RESPONSE_ID`: if applicable, the user response given
|
|
through the current dialog
|
|
|
|
* `BAZAAR_APPID`: if applicable, the appid of the entry Bazaar is currently
|
|
dealing with. Use this for hooks that are not related to transactions. If your
|
|
hook deals with transactions, such as `before-transaction` or
|
|
`after-transaction`, use `BAZAAR_TS_APPID` instead.
|
|
|
|
* `BAZAAR_TS_APPID`: if applicable, the appid of the entry Bazaar is currently
|
|
dealing with. Use this for hooks that are related to transactions. If your
|
|
hook does not deal with transactions, such as `view-app`, use `BAZAAR_APPID`
|
|
instead.
|
|
|
|
* `BAZAAR_TS_TYPE`: if applicable, the type of transaction being run. Can be
|
|
"install", "update", or "removal".
|
|
|
|
* `BAZAAR_HOOK_STAGE`: the stage at which the hook is running. This will
|
|
indicate what the shell body is instructed to do at this time. The shell body
|
|
must respond by outputting to stdout with a valid answer; the structure of a
|
|
valid answer will depend on the stage, and if the structure is not valid the
|
|
hook will be abandoned. The shell body might be run multiple times by Bazaar
|
|
over the course of a hook with this variable set to differing values in order
|
|
know how to orchestrate events in the UI, so the shell body must be able to
|
|
branch depending on the value. The value may be any of the following:
|
|
|
|
* `setup`: the hook is starting. Respond with "ok" to continue the
|
|
execution of this hook, or "pass" to skip it and move on to the
|
|
next registered hook
|
|
|
|
* `setup-dialog` Bazaar is ready to ask the user a question with one of the
|
|
dialogs you've defined inside the "dialogs" mapping. `BAZAAR_HOOK_DIALOG_ID`
|
|
will tell you which one. Respond with "ok" to spawn the dialog, or "pass" to
|
|
skip the dialog.
|
|
|
|
* `teardown-dialog` Bazaar has received input from the user after asking them
|
|
a question with one of the dialogs you've defined inside the "dialogs"
|
|
mapping. `BAZAAR_HOOK_DIALOG_ID` will tell you which one.
|
|
`BAZAAR_HOOK_DIALOG_RESPONSE_ID` will tell you the response the user chose.
|
|
Respond with "ok" to continue, or "abort" to stop the execution of this
|
|
hook.
|
|
|
|
* `catch` One of your dialogs has aborted. This is your chance to handle the
|
|
error. Respond with "recover" to continue, or "abort" to confirm that the
|
|
execution of this hook should indeed skip to the teardown stage.
|
|
|
|
* `action` Everything so far has gone according to plan, so it is time to take
|
|
whatever external action this hook exists for. Bazaar requires no response
|
|
at this time.
|
|
|
|
* `teardown` The hook is cleaning up. Respond with "continue" to propagate the
|
|
signal emission to lower priority hooks, or "stop" to indicate the emission
|
|
should stop. Alternatively, if this hook type should hint to Bazaar an
|
|
action to take (such as the "before-transaction" hook), respond with
|
|
"confirm" to hint that the action should be taken, or "deny" to prevent the
|
|
action from being taken. Both "confirm" and "deny" imply the effect of
|
|
"stop", and "stop" implies "confirm".
|
|
|
|
### Example
|
|
|
|
Hooks are defined in the main yaml config as indicated by the
|
|
`hardcoded_main_config_path` comptime var. Here is a basic example demonstrating
|
|
how to define a hook:
|
|
|
|
`hardcoded_main_config_path`:
|
|
```yaml
|
|
hooks:
|
|
- id: handle-jetbrains
|
|
when: before-transaction
|
|
dialogs:
|
|
- id: jetbrains-warning
|
|
title: >-
|
|
JetBrains IDEs are not supported in this format
|
|
# If true, render inline markup commands in body; see
|
|
# https://docs.gtk.org/Pango/pango_markup.html
|
|
body-use-markup: true
|
|
body: >-
|
|
This is a <a href="https://www.jetbrains.com/">JetBrains</a>
|
|
application and is not officially supported on Flatpak. We
|
|
recommend using the Toolbox app to manage JetBrains IDEs.
|
|
# Determines which option will be assumed if the user hits the
|
|
# escape key or otherwise cancels the dialog
|
|
default-response-id: cancel
|
|
options:
|
|
- id: cancel
|
|
string: "Cancel"
|
|
- id: goto-web
|
|
string: "Download JetBrains Toolbox"
|
|
# can be "destructive" or "suggested" or omit for no
|
|
# styling
|
|
style: suggested
|
|
shell: exec /absolute/path/to/bazaar-jetbrains-hook.bash
|
|
# This gives you the opportunity to add a basic regex check on an incoming
|
|
# appid before incurring the overhead of spawning a subprocess. This
|
|
# improves performance and reduces script boilerplate for long lists of
|
|
# hooks that execute on specific appids.
|
|
check-appid-regex: ^com\.jetbrains\..*$
|
|
```
|
|
|
|
`/absolute/path/to/bazaar-jetbrains-hook.bash`:
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
|
|
|
|
handle_setup_stage() {
|
|
|
|
# only proceed if the user is installing something
|
|
if [ "$BAZAAR_TS_TYPE" = install ]; then
|
|
case "$BAZAAR_TS_APPID" in
|
|
com\.jetbrains\.*)
|
|
# since the appid belongs to jetbrains, we continue
|
|
# with the hook
|
|
echo 'ok'
|
|
;;
|
|
*)
|
|
# otherwise, skip this hook
|
|
echo 'pass'
|
|
;;
|
|
esac
|
|
else
|
|
echo 'pass'
|
|
fi
|
|
|
|
}
|
|
|
|
|
|
handle_setup_dialog_stage() {
|
|
|
|
# we don't need to do anything here right now, just let Bazaar
|
|
# know we should continue setting up the dialog
|
|
echo 'ok'
|
|
|
|
}
|
|
|
|
|
|
handle_teardown_dialog_stage() {
|
|
|
|
case "$BAZAAR_HOOK_DIALOG_RESPONSE_ID" in
|
|
goto-web)
|
|
# if the user pressed "Download JetBrains Toolbox",
|
|
# continue
|
|
echo 'ok'
|
|
;;
|
|
*)
|
|
# otherwise, let's not do anything
|
|
echo 'abort'
|
|
;;
|
|
esac
|
|
|
|
}
|
|
|
|
|
|
handle_catch_stage() {
|
|
|
|
# this only happens if the `teardown-dialog` stage echoed "abort",
|
|
# we could echo "recover" at this point to still go to the
|
|
# `action` stage, but we have no reason to do that right now
|
|
echo 'abort'
|
|
|
|
}
|
|
|
|
|
|
handle_action_stage() {
|
|
|
|
# this is where we do the thing! it is important to use `nohup`
|
|
# here so bazaar doesn't hang
|
|
nohup xdg-open 'https://www.jetbrains.com/toolbox-app/'
|
|
|
|
}
|
|
|
|
|
|
handle_teardown_stage() {
|
|
|
|
# Let's always prevent the user from installing JetBrains stuff
|
|
echo 'deny'
|
|
|
|
}
|
|
|
|
|
|
# Branch based on the stage
|
|
case "$BAZAAR_HOOK_STAGE" in
|
|
setup) handle_setup_stage ;;
|
|
setup-dialog) handle_setup_dialog_stage ;;
|
|
teardown-dialog) handle_teardown_dialog_stage ;;
|
|
catch) handle_catch_stage ;;
|
|
action) handle_action_stage ;;
|
|
teardown) handle_teardown_stage ;;
|
|
esac
|
|
|
|
|
|
# exit successfully
|
|
exit 0
|
|
```
|
|
|
|
## Search Biases
|
|
|
|
Search biases are a mechanism provided by Bazaar to influence search results.
|
|
Given a regex string with which to match a search query, a bias can replace the
|
|
matched text with a new string and/or adjust the scores of certain appids
|
|
according to a defined function if a match occurs. This is particularly useful
|
|
in the following cases:
|
|
|
|
* An application is, for example, an image editor, but doesn't show up in the
|
|
results for "image editor" because its metadata doesn't contain those search
|
|
tokens for whatever reason. A search bias can ensure that the app appears
|
|
despite this.
|
|
|
|
* You want an abbreviation or phrase to be expanded into a version which is more
|
|
likely to yield better results. For example, Bazaar hardcodes the expansion of
|
|
the abbreviation `dl` to `download`, which is more helpful when searching
|
|
metadata.
|
|
|
|
### Boost Functions
|
|
|
|
Right now, there are two kinds of boost functions you can specify to influence
|
|
the score of certain appids in the event of a regex match: linear and
|
|
exponential:
|
|
|
|
#### Linear
|
|
|
|
Linear functions require a `slope` and a `y-intercept` and are evaluated like
|
|
this:
|
|
|
|
```
|
|
new-score = y-intercept + (slope * original-score)
|
|
```
|
|
|
|
#### Exponential
|
|
|
|
Exponential functions require a `factor` and a `y-intercept` and are evaluated
|
|
like this:
|
|
|
|
```
|
|
new-score = y-intercept * (factor ^ original-score)
|
|
```
|
|
|
|
### Examples
|
|
|
|
Search biases are defined in the main yaml config as indicated by the
|
|
`hardcoded_main_config_path` comptime var. Here is a basic example demonstrating
|
|
how to define search biases:
|
|
|
|
```yaml
|
|
search-biases:
|
|
# Brief regex review:
|
|
# `^` indicates the beginning of the string
|
|
# `$` indicates the end of the string
|
|
# `\b` indicates a word boundary
|
|
# `(?i)` means case insensitive
|
|
|
|
# Convert queries like "smb server" to "samba server"
|
|
- regex: \b(?i)smb\b
|
|
convert-to: samba
|
|
|
|
# Give your favorite matrix clients a simple boost of 100.0 to their score
|
|
- regex: \b(?i)matrix\b
|
|
boost-appids:
|
|
- org.gnome.Fractal
|
|
- im.riot.Riot
|
|
linear-boost:
|
|
slope: 1.0
|
|
y-intercept: 100.0
|
|
|
|
# Convert the search _and_ boost appids
|
|
- regex: ^(?i)deck$
|
|
convert-to: steam deck
|
|
boost-appids:
|
|
- com.github.Matoking.protontricks
|
|
- com.steamgriddb.steam-rom-manager
|
|
- com.valvesoftware.SteamLink
|
|
linear-boost:
|
|
slope: 1.2
|
|
y-intercept: 20.0
|
|
|
|
# Biases are applied in the order that you specify them, so in both the case
|
|
# that the user types "deck" or "steam deck launcher", the following will be
|
|
# applied:
|
|
- regex: \bsteam deck\b
|
|
boost-appids:
|
|
- net.retrodeck.retrodeck
|
|
exponential-boost:
|
|
factor: 2.0
|
|
y-intercept: 5.0
|
|
```
|
|
|
|
Pro tip: pressing `ctrl-alt-d` in Bazaar activates debug mode, which enables you
|
|
to see the scores of app results on the search page. This is useful for
|
|
debugging search biases!
|
|
|
|
## Translations in YAML Configs
|
|
|
|
For any string scalar property in YAML configs parsed by bazaar, you can
|
|
optionally provide a map of language code ids -> translated strings. This is for
|
|
strings only, thus it doesn't apply to scalars which are explicitly parsed as
|
|
numbers, etc.
|
|
|
|
For instance, this is valid:
|
|
|
|
```yaml
|
|
# ...
|
|
category:
|
|
title: "My Favorite Apps"
|
|
subtitle: "These are really good and you should download them!"
|
|
# ...
|
|
```
|
|
|
|
This is also valid:
|
|
|
|
```yaml
|
|
# ...
|
|
category:
|
|
title:
|
|
en: "My Favorite Apps"
|
|
es: "Mis Aplicaciones Favoritas"
|
|
ko: "내가 가장 좋아하는 앱들"
|
|
subtitle:
|
|
en: "These are really good and you should download them!"
|
|
es: "¡Son realmente buenos y deberías descargarlos!"
|
|
ko: "이것들은 정말 좋으니 꼭 다운로드하세요!"
|
|
# ...
|
|
```
|
|
|
|
(I just used google translate for these, sorry if they are bad)
|