search

anyrun-org / anyrun

A wayland native, highly customizable runner.
GNU General Public License v3.0
560 stars 44 forks source link

readme

Anyrun

A wayland native krunner-like runner, made with customizability in mind.

Features

Usage

Dependencies

Anyrun mainly depends various GTK libraries, and rust of course for building the project. Rust you can get with rustup. The rest are statically linked in the binary. Here are the libraries you need to have to build & run it:

Installation

Packaging status

Nix

You can use the flake:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    anyrun.url = "github:anyrun-org/anyrun";
    anyrun.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = { self, nixpkgs, anyrun }: let
  in {
    nixosConfigurations.HOSTNAME = nixpkgs.lib.nixosSystem {
      # ...

      environment.systemPackages = [ anyrun.packages.${system}.anyrun ];

      # ...
    };
  };
}

The flake provides multiple packages:

Home-Manager module

The anyrun flake exposes a Home-Manager module as homeManagerModules.default. You use it in your system like this:

{
  programs.anyrun = {
    enable = true;
    config = {
      plugins = [
        # An array of all the plugins you want, which either can be paths to the .so files, or their packages
        inputs.anyrun.packages.${pkgs.system}.applications
        ./some_plugin.so
        "${inputs.anyrun.packages.${pkgs.system}.anyrun-with-all-plugins}/lib/kidex"
      ];
      x = { fraction = 0.5; };
      y = { fraction = 0.3; };
      width = { fraction = 0.3; };
      hideIcons = false;
      ignoreExclusiveZones = false;
      layer = "overlay";
      hidePluginInfo = false;
      closeOnClick = false;
      showResultsImmediately = false;
      maxEntries = null;
    };
    extraCss = ''
      .some_class {
        background: red;
      }
    '';

    extraConfigFiles."some-plugin.ron".text = ''
      Config(
        // for any other plugin
        // this file will be put in ~/.config/anyrun/some-plugin.ron
        // refer to docs of xdg.configFile for available options
      )
    '';
  };
}

You might also want to use the binary cache to avoid building locally.

nix.settings = {
    builders-use-substitutes = true;
    # extra substituters to add
    extra-substituters = [
        "https://anyrun.cachix.org"
    ];

    extra-trusted-public-keys = [
        "anyrun.cachix.org-1:pqBobmOjI7nKlsUMV25u9QHa9btJK65/C8vnO3p346s="
    ];
};

Manual installation

Make sure all of the dependencies are installed, and then run the following commands in order:

git clone https://github.com/Kirottu/anyrun.git # Clone the repository
cd anyrun # Change the active directory to it
cargo build --release # Build all the packages
cargo install --path anyrun/ # Install the anyrun binary
mkdir -p ~/.config/anyrun/plugins # Create the config directory and the plugins subdirectory
cp target/release/*.so ~/.config/anyrun/plugins # Copy all of the built plugins to the correct directory
cp examples/config.ron ~/.config/anyrun/config.ron # Copy the default config file

Plugins

Anyrun requires plugins to function, as they provide the results for input. The list of plugins in this repository is as follows:

Configuration

The default configuration directory is $HOME/.config/anyrun the structure of the config directory is as follows and should be respected by plugins:

- anyrun
  - plugins
    <plugin dynamic libraries>
  config.ron
  style.css
  <any plugin specific config files>

The default config file contains the default values, and annotates all configuration options with comments on what they are and how to use them.

Styling

Anyrun supports GTK+ CSS styling. The names for the different widgets and widgets associated with them are as follows:

Arguments

The custom arguments for anyrun are as follows:

The rest of the arguments are automatically generated based on the config, and can be used to override configuration parameters. For example if you want to temporarily only run the Applications and Symbols plugins on the top side of the screen, you would run anyrun --plugins libapplications.so --plugins libsymbols.so --position top.

Plugin development

The plugin API is intentionally very simple to use. This is all you need for a plugin:

Cargo.toml:

#[package] omitted
[lib]
crate-type = ["cdylib"] # Required to build a dynamic library that can be loaded by anyrun

[dependencies]
anyrun-plugin = { git = "https://github.com/Kirottu/anyrun" }
abi_stable = "0.11.1"
# Any other dependencies you may have

lib.rs:

use abi_stable::std_types::{RString, RVec, ROption};
use anyrun_plugin::*;

#[init]
fn init(config_dir: RString) {
  // Your initialization code. This is run in another thread.
  // The return type is the data you want to share between functions
}

#[info]
fn info() -> PluginInfo {
  PluginInfo {
    name: "Demo".into(),
    icon: "help-about".into(), // Icon from the icon theme
  }
}

#[get_matches]
fn get_matches(input: RString) -> RVec<Match> {
  // The logic to get matches from the input text in the `input` argument.
  // The `data` is a mutable reference to the shared data type later specified.
  vec![Match {
    title: "Test match".into(),
    icon: ROption::RSome("help-about".into()),
    use_pango: false,
    description: ROption::RSome("Test match for the plugin API demo".into()),
    id: ROption::RNone, // The ID can be used for identifying the match later, is not required
  }].into()
}

#[handler]
fn handler(selection: Match) -> HandleResult {
  // Handle the selected match and return how anyrun should proceed
  HandleResult::Close
}

And that's it! That's all of the API needed to make runners. Refer to the plugins in the plugins folder for more examples.