Repository files navigation

JavaScript has npm, Ruby has Gems, Python has pip and now Shell has bpkg!

bpkg is a lightweight bash package manager. It takes care of fetching the shell scripts, installing them appropriately, setting the execution permission and more.

You can install shell scripts globally (on${PREFIX:-/usr/local/bin}) or use them on aper-project basis (on${BPKG_DEPS:-./deps/}), as a lazy-man "copy and paste".

• Install
  • 0. Dependencies
  • 1. Install script
  • 2. clib
  • 3. Source Code
• Usage
  • Installing packages
  • Packages With Dependencies
  • Running packages withbpkg
  • Retrieving package info
• Package details
• bpkg.json
  • name
  • version (optional)
  • description
  • global
  • install
  • scripts
  • files (optional)
  • dependencies (optional)
  • dependencies-dev (optional)
  • commands (optional)
  • commands-description (optional)
• Packaging best practices
  • Package exports
• Sponsors
  • Contributors
  • Backers
• License

You can installbpkg from three distinct ways:

• curl
• coreutils

Our install script is the simplest way. It takes care of everything for you, placingbpkg and related scripts on/usr/local/bin.

You can installbpkg with theget.bpkg.sh endpoint:

curl -Lo - get.bpkg.sh| bash

Or optionally paste the following on your shell and you're good to go:

curl -Lo-"https://raw.githubusercontent.com/bpkg/bpkg/master/setup.sh"| bash

or by tag/version

curl -Lo-"https://raw.githubusercontent.com/bpkg/bpkg/1.0.15/setup.sh"| bash

clib is a package manager for C projects. If you already have it, installingbpkg is a simple matter of:

clib install bpkg/bpkg

To directly installbpkg from its source code you have to clone its repository and run thesetup.sh script:

git clone https://github.com/bpkg/bpkg.gitcd bpkg./setup.sh# Will install bpkg in $HOME/.local/binsudo ./setup.sh# Will install bpkg in /usr/local/bin.PREFIX=/my/custom/directory ./setup.sh# Will install bpkg in a custom directory.

You usebpkg by simply sending commands, pretty much likenpm orpip.

Packages can either be global (on${PREFIX:-/usr/local/bin} if installed as root or${PREFIX:-$HOME/.local/bin} otherwize) or local (under${BPKG_DEPS:-./deps}).

For example, here's aglobal install for the current user of theterm package:

bpkg install term -gterm

And the same package as alocal install:

bpkg install term./deps/term/term.sh

After a local install theterm.sh script is copied asterm to thedeps/bin directory, you can add this directory to thePATH with

export PATH=$PATH:/path_to_bkpg/deps/bin

As a bonus, you can specify aspecific version:

bpkg install jwerle/suggest.sh@0.0.1 -g

Note: to do that the packagesmust be tagged releases on the repository.

You can alsoinstall packages without abpkg.json (orpackage.json).As long as there is aMakefile in the repository it will try to invokemake install as long as the-g or--global flags are set when invokingbpkg install.

For example you could installgit-standup with an omittedbpkg.json (orpackage.json) because of theMakefile and theinstall target found in it.

bpkg install stephenmathieson/git-standup -g    warn: bpkg.json doesn`t exist    warn: package.json doesn`t exist    warn: Trying`make install'...    info: install: `make install'cp -f git-standup /usr/local/bin

You can install a packages dependencies with thebpkg getdeps command. These will recursively install indeps/ sub-folders to resolve all dependencies.

Note: There is no protection against circular dependencies, so be careful!

You can run a package script withbpkg run which will install yourpackage globally and execute it as a command

After installing a package, you can obtain info from it usingbpkg.

Supposing you're on the root of a package directory, the following commands show that package metadata:

# Asking for single informationbpkg package name"bpkg"bpkg package version"0.0.5"# Dumping all the metadatabpkg package["name"]"bpkg"["version"]"0.0.5"["description"]"Lightweight bash package manager"["global"]true["install"]"make install"

Here we lay down some info on the structure of a package.

Every package must have a file calledbpkg.json (for backward-compatibilitypackage.json can also be used); it specifies package metadata on theJSON format.

Here's an example of a well-formedbpkg.json:

{"name":"term","version":"0.0.1","description":"Terminal utility functions","scripts": ["term.sh" ],"install":"make install"}

All fields are mandatory except when noted.Here's a detailed explanation on all fields:

Thename attribute is required as it is used to tellbpkg where to put it in thedeps/ directory in you project.

"name":"my-script"

Theversion attribute is not required but can be useful. It should correspond to the version that is associated with the installed package.

"version":"0.0.1"

A human readable description of what the package offers for functionality.

"description":"This script makes monkeys jump out of your keyboard"

Indicates that the package is only intended to be install as a script. This allows the omission of the-g or--global flag during installation.

"global":"true"

Shell script used to invoke in the install script. This is required if theglobal attribute is set totrue or if the-g or--global flags are provided.

"install":"make install"

This is an array of scripts that will be installed into a project.

"scripts": ["script.sh"]

This is an array of non-script files that will be installed into a project.

"files": ["bar.txt","foo.txt"]

This is a hash of dependencies. The keys are the package names, and the values are the version specifiers. If you want the latest code use'master' in the version specifier. Otherwise, use a tagged release identifier. This works the same asbpkg install's package/version specifiers.

"dependencies": {"term":"0.0.1"  }

This is a hash of dependencies only needed during development. Like thedependencies array, the keys are the package names, and the values are the version specifiers;'master' or a tagged release can be used as the identifier. These development dependencies are installed by adding the-d or--dev flags to thebpkg install command.

"dependencies-dev": {"term":"0.0.1"  }

This is a hash of commands. The keys are the names of the commands and the values are the commands to execute in a shell. The commands can be called from the command line withbpkg run followed by the command name.

"commands": {"say-hello":"echo\"Hello $1\""  }

The commands are run witheval, which runs the command as if on the command line. Commands can contain environment variables, and supportsshell features (includingspecial parameters andshell expansions). Passed parameters (on the command line after the command name) can be accessed in the command by using$@ or$1.

$ bpkg run say-hello"Bash Package Manager"Hello Bash Package Manager

This is a hash of descriptions for configured commands. The keys are the names of the commands and the values are the descriptions for the specified commands. The command descriptions can be listed on the command line by providing the-l or--list flags after thebpkg run command.

"commands-description": {"say-hello":"Output hello to provided name (ex: bpkg run say-hello John)"  }

These are guidelines that we strongly encourage developers to follow.

It's nice to have a bash package that can be used in the terminal and also be invoked as a command line function. To achieve this the exporting of your functionalityshould follow this pattern:

if [[${BASH_SOURCE[0]}!="$0" ]];thenexport -f my_scriptelse  my_script"${@}"exit$?fi

This allows a user tosource your script or invoke as a script.

# Running as a script./my_script.sh some args --blah# Sourcing the scriptsource my_script.shmy_script some more args --blah

bpkg wouldn't be where it is today without the help of its authors, contributors, and sponsors:

• @socketsupply (socketsupply.co)
• @little-core-labs
• @littlstar (littlstar.com)
• @spotify (spotify.com)

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]

This project exists thanks to all the people who contribute. [Contribute].

Thank you to all our backers! 🙏 [Become a backer]

bpkg is released under theMIT license.

See fileLICENSE for a more detailed description of its terms.