Pearl

|Project Status|Donation|Communication| |:-----------:|:--------:|:-----------:| | | | |

Table of Contents

Description
Quickstart
Installation
- Dependencies
- Linux
- OSX
Create your own Pearl package
Create your own Pearl repository
Comparison with alternative solutions
Troubleshooting
Contributing
Donating
Authors

Description

Pearl is a lightweight package manager for automating reproducible environments between different systems (Linux and OSX). It can be used for dotfiles, plugins, programs and any form of code accessible via git.

As soon as a package gets installed, its content can be activated out of the box according to certain events, like, for instance, a shell startup (Bash, Zsh or Fish) or an editor startup (Vim or Emacs). This is possible via a smart and simple hook mechanism that integrates the package content within the Pearl ecosystem.

The main advantages on using Pearl are:

Create your own Pearl package in a very simple way.
Full control and sync of your dotfiles across different systems.
Automatic bootstrap of the package content whenever shells or editors get started.
Access to a wide range of existing packages via the OPH (Official Pearl Hub).
Allows to create your own shareable package repository.
Comparison with alternative solutions
Stable codebase with 100+ unit tests and exhaustive integration tests via Travis for Linux and OSX.
Small number of dependencies needed in order to ensure compatibility with most of the systems.

Quickstart

There are two main use cases for Pearl which will be explained here below:

Use case 1: Create custom package

The following example creates a Pearl package containing a git dotfile and a simple executable available as soon as the package gets installed.

$> pearl create mydotfiles ~/dotfiles

This will create a directory pearl-config in ~/dotfiles containing all the templates to help you start writing a Pearl package. ~/dotfiles does not need to be an empty directory.

Additionally, the local repository in $XDG_CONFIG_HOME/pearl/pearl.conf (defaults to ~/.config/pearl/pearl.conf) will be updated with the new package entry called mydotfiles. This tells to Pearl where to look for the package:

$> cat ~/.config/pearl/pearl.conf
...
...
PEARL_PACKAGES["mydotfiles"] = {"url": "~/dotfiles"}

Place the git config inside ~/dotfiles directory:

$> cd ~/dotfiles
$> echo -e "[alias]\n    cfg = config" > gitconfig
$> echo -e "#!/bin/bash\necho Hello World!" > hello
$> chmod +x hello

You need now to give instructions about how to link the gitconfig file into the system and make the executable available in PATH. This is possible through the pearl-config/hooks.sh file. Just update it with the following:

post_install() {
    link git "${PEARL_PKGDIR}/gitconfig"
    link_to_path "${PEARL_PKGDIR}/hello"
    return 0
}

post_update() {
    post_install
}

pre_remove() {
    unlink git "${PEARL_PKGDIR}/gitconfig"
    unlink_from_path "${PEARL_PKGDIR}/hello"
    return 0
}

This tells to Pearl to link the git config located in "${PEARL_PKGDIR}/gitconfig" (${PEARL_PKGDIR} is a builtin variable) to the git program just after the package installation. Also, hooks.sh will link the executable hello by creating a symlink and make it visible to PATH env variable. Conversely, before removal, the hooks file tells to unlink the git config file and remove the symlink.

Now, just install the package and you will see the changes already reflected:

$> pearl install mydotfiles
$> git cfg -l
...
...
$> hello
Hello World!

Once the package is completed, you can upload it to a git repository and just fetch it from there by updating ~/.config/pearl/pearl.conf:

$> cat ~/.config/pearl/pearl.conf
...
...
PEARL_PACKAGES["mydotfiles"] = {"url": "https://github.com/pearluser/mydotfiles.git"}

There are way more things you can do with Pearl! For more details about the pearl-config content, look at the section below.

Use case 2: Use Pearl Hub repository

You can just use existing packages from the Pearl Hub repository. It contains a big list of packages about dotfiles, programs and plugins for many known applications.

For instance, look to the entire list of packages:

$> pearl list

If interested to search only for dotfiles:

$> pearl search dotfiles
pearl/dot-gtk 
    Awesome gtk dotfiles
pearl/kyrat 
    20 lines script that brings dotfiles in a ssh session
pearl/dot-mutt 
    Awesome Mutt dotfiles
pearl/dot-emacs 
    Awesome emacs dotfiles
pearl/dot-git 
    Awesome git dotfiles
pearl/dot-screen 
    Awesome screen dotfiles
pearl/dot-tmux
    Awesome Tmux dotfiles
pearl/dot-vim
    Awesome vim dotfiles
pearl/dot-firefox
    Awesome Firefox dotfiles
pearl/dot-terms
    Awesome terms dotfiles (i.e. urxvt)
pearl/dot-bash
    Awesome bash dotfiles

Recommended Pearl Hub packages to install:

Installation

Dependencies

Before installing Pearl be sure that all dependencies are properly installed in your system. The Pearl dependencies are the following:

Mandatory

PLEASE NOTE: Tests may be performed on different versions from the ones listed above. To know which versions are truly tested have a look at latest Travis executions here.

Optional

The following are not mandatory dependencies but can be handy to have for the hook functions in Pearl package. All the Linux distributions have these dependencies already installed.

Shells supported

Pearl supports the following shells:

PLEASE NOTE: Tests may be performed on different versions from the ones listed above. To know which versions are truly tested have a look at latest Travis executions here.

Linux

Arch Linux

Pearl can be installed in Arch Linux through AUR. The package is pearl-git.

For example, to install Pearl via yay AUR helper:

$> yay -S pearl-git

Any other AUR helpers can be found here.

Other Linux distributions

Assuming all Pearl dependencies are properly installed in the system, to install Pearl you can use the pip command:

$> sudo python3 -m pip install pearl
$> pearl init

Make sure to update PATH environment variable if needed (pearl is typically located to /usr/bin). The idempotent init command will create the $PEARL_HOME directory and the new pearl configuration files from template.

OSX

In order to install all Pearl dependencies, you first need to install Homebrew.

To install all the needed dependencies via Homebrew:

$> brew update
$> brew install bash git coreutils grep gnu-sed python

To install Pearl you can use the pip command:

$> pip3 install pearl
$> pearl init

IMPORTANT NOTE: Pearl gets loaded through ~/.bashrc. The problem is that in OSX, the terminal opens a login shell and only ~/.bash_profile will get executed. Run the following only if ~/.bashrc is not loaded within ~/.bash_profile file:

$> echo "[[ -f $HOME/.bashrc ]] && source $HOME/.bashrc" >> ~/.bash_profile

This will make sure that ~/.bashrc will run at shell startup.

Create your own Pearl package

Any git repository is already a Pearl package. For instance, in

Pearl

Install / Use

README

Pearl

Description

Quickstart

Use case 1: Create custom package

Use case 2: Use Pearl Hub repository

Recommended Pearl Hub packages to install:

Installation

Dependencies

Mandatory

Optional

Shells supported

Linux

Arch Linux

Other Linux distributions

OSX

Create your own Pearl package