Skip to content

Latest commit

 

History

History
128 lines (90 loc) · 4.18 KB

README.md

File metadata and controls

128 lines (90 loc) · 4.18 KB

wrapperize

This is a small Linux utility program that creates wrappers for arbitrary executables to launch them with a predefined set of arguments and/or environment variables, without modifying the original executable.

This is primarily designed for Arch Linux. By default, the program will generate pacman hooks for the wrapped executable so that the wrapper is automatically recreated whenever the package associated with the wrapper is updated, reinstalled, or removed. This behavior can be disabled via a --nohooks flag so executables not managed by pacman (such as a script in /home) can be wrapped without requiring root.

  1. Prerequisites
  2. Installation
  3. Usage
  4. Examples
  5. How it works

Prerequisites

  • Rust 1.93 or later.

Installation

cargo install --path wrapperize

The binary will be installed to ~/.cargo/bin/wrapperize.
~/.cargo/bin must be added to your $PATH if it isn't already.

Usage

$ wrapperize --help
Usage: wrapperize [-a <arg...>] [-e <env...>] [--nohooks] [--passthrough-args-first] [--keep-relative] [--] <executable_path>

Positional Arguments:
  executable_path   path of the executable to wrap

Options:
  -a, --arg         an additional argument to launch the executable with; can be
                    used multiple times
  -e, --env         an environment variable in the format of `ENV=value` to
                    launch the executable with; can be used multiple times
  --nohooks         do not generate hooks for pacman; intended to be used for
                    paths not managed by pacman (such as `/home`)
  --passthrough-args-first
                    place the wrapper arguments after the passthrough arguments,
                    so they are seen last by the wrapped executable
  --keep-relative   prevent the provided path from being canonicalized (made
                    absolute); this can only be used in combination with
                    `--nohooks` to minimize the chance of a path-related attack
  --help, help      display usage information

Examples

Basic wrapping

Wrap /usr/bin/vim so it always launches with --servername=MYVIM:

sudo wrapperize /usr/bin/vim -a --servername=MYVIM

Multiple arguments

Add several arguments:

sudo wrapperize /usr/bin/gcc \
  -a -O3 \
  -a -march=native

Environment variables

Set environment variables when launching the executable:

sudo wrapperize /usr/bin/ssh \
  -e SSH_AUTH_SOCK=/run/user/1000/keyring/ssh \
  -e SSH_ASKPASS=/usr/bin/ssh-askpass

Passthrough order

By default the wrapper’s predefined arguments are placed before any additional arguments that may be passed to the wrapper. If you need them after, specify the --passthrough-args-first flag during wrapper creation:

sudo wrapperize /usr/bin/python3 \
  -a -O \
  --passthrough-args-first

Skipping pacman hooks

If the binary isn’t managed by pacman (e.g., a script in /home), skip the hook generation:

wrapperize /home/user/myscript.sh -e MY_VAR=foo --nohooks

How it works

Wrapper script

The original executable is renamed to a hidden file, and the generated wrapper script is created with the executable's original name:

/usr/bin/.vim-unwrapped  ← original executable
/usr/bin/vim             ← wrapper (generated by wrapperize)

The wrapper script will generally look like this (assuming both environment variables and arguments were defined during wrapper creation):

#!/usr/bin/env bash
export ENV1="value1"
export ENV2="value2"
exec "/usr/bin/.vim-unwrapped" --arg1 --arg2 "$@"

Pacman hooks

Unless skipped via the --nohooks flag, the following pacman hooks will be created in /etc/pacman.d/hooks:

  1. Install/Update hook – runs after the executable's associated package is installed or upgraded to recreate the wrapper.
    • A shell script is also generated next to this hook that is called by it to actually install the wrapper.
  2. Removal hook – runs after the executable's associated package is removed to delete the wrapper, pacman hooks, and the shell script created for the install/update hook.