Guide to creating a BPKG package

creating-bpkg-package.md

Guide to creating a BPKG package

This guide outlines the steps to create the Bpkg package, using a
template "bpkg-template-one-file" from a GitHub repository.

The simplest package includes:

• A single script file named example_script.sh.
• A single command, excmd (short for "example command")
  That can be used after installation either in the command line
  (for user terminal use) or within scripts (for in-script use).

Bpkg is a lightweight bash package manager that facilitates the discovery,
installation, and management of bash scripts and functions. It's a useful
tool for both developers and users looking to distribute or utilize bash
utilities in a manageable way. With Bpkg, you can easily share your
bash scripts with a wider audience while also benefiting from the shared
scripts of others. You can find its repository on GitHub.

Each section provides detailed explanations and examples to guide you through
the package creation process. By the end of this guide, you'll have a
well-structured Bpkg package ready for distribution.

0. Pre-Requisites

-1. Console Requirements:

• Linux: A simple console will suffice.
• Windows: A console with a Unix-like environment is needed. Here are several options:
  • WSL (Windows Subsystem for Linux): A better choice for full Linux console support.
  • Cygwin: An attempt to create a complete UNIX/POSIX environment on Windows.
  • MSYS2: A software distro and building platform for Windows, providing MinGW-w64 and other tools.
  • MinGW-w64: A development environment for Windows targeting the GNU and UNIX compatibility.
  • Git Bash: Offers Bash environment and Git command line features.

-2. Software Requirements:

• Ensure you have Git installed on your machine.
• Ensure you have bpkg installed on your machine.

-3. Account Requirements:

• A GitHub account to host your package repository.

1. Clone template repository

$ git clone https://github.com/null-galaxy/bpkg-template-one-file.git new_pack

In this step, you are cloning a template repository from GitHub to your
local machine. This particular repository, bpkg-template-one-file,
is designed to provide a skeleton structure for creating a new bpkg
package. The command above clones the repository into a new directory
new_pack on your local machine, which you can then modify to
suit your package's needs.

We are using a template from a GitHub repository called "bpkg-template-one-file".
This template includes various files including licensing and a separate
installation script, which can be handy for systems without an installed make.
However, if you prefer a more minimal setup, there are two other repositories
that contain only the essential files (a script file and an install command file):

• For installation via Makefile, see
  repo:bpkg-make-min-example-linux.
• For installation via a command specified in a JSON file, see
  repo:bpkg-json-min-example-linux.

2. Explore Repository Contents

The template repository contains the following items, providing a foundational structure for your package. This streamlines the package creation process, saving time on setting up the basic framework, and allowing focus on writing the actual code for your package.

• Makefile: Manages build tasks.
• bpkg.json (or other relevant configuration file): Specifies package metadata.
• README.md: Provides documentation.
• install.sh: Handles the installation of your package.
• LICENSE.md: Specifies the terms under which your package is shared.
• Other Boilerplate Files or Directories: Any other common files or directories to bpkg packages.

3. Write Script Code

3.1. Script Creation

For example, a simple example command in function excmd():

#!/usr/bin/env bash

# main entrance
excmd () {
    echo 'Run example_script.sh installed via BPKG'
}

3.2. Exporting Function

• In the script example_script.sh, the excmd function serves as the main entry point to your script. When the script is sourced (rather than executed), the excmd function is exported to the user's shell environment, making it available for direct use as a command.
• The script checks if it's being sourced by comparing ${BASH_SOURCE[0]} to $0. If they are not equal, the script is being executed directly, and excmd is called with any supplied arguments ("${@}").
• If they are equal, the script is being sourced, and excmd is exported using the export -f command, making it available as a command in the user's current shell session.
• This design allows the script to be used in two ways:
  1. As a script that can be executed directly from the command line.
  2. As a sourceable script that exports functionality to the current shell session.
• This flexibility can be beneficial, for example, when you want to provide a function that users can use as part of their shell environment, or when you want to provide a script that can be executed as a standalone utility.

# detect if being sourced and
# export if so, else execute
# main function with args
if [[ ${BASH_SOURCE[0]} != $0 ]]; then
    export -f excmd
else
    excmd "${@}"
    exit $?
fi

4. Customize Template Files

• Makefile:
  • Modify the Makefile to match your project's build and installation parameters.
• bpkg.json - configuration File:
  • Update the bpkg.json file (or any other relevant configuration file) to include your package details such as name, version, and dependencies.
• README.md - documentation:
  • Update file to provide clear instructions on how to install, use, and contribute to your package. Include any other relevant information that would help users and contributors understand the purpose and functionality of your package.

5. Create new GitHub repository

• Create a new repository on GitHub.
• Add the remote repository to your local repository with the command:

$ git remote add origin https://github.com/your-username/your-repo.git

• Upload your local project to the remote repository with the commands:

$ git add .
$ git commit -m "Initial commit"
$ git push -u origin master

6. Test your package

6.1. Package Installation:

• Clone your package using the bpkg command.
• Ensure that the package installs and operates correctly:

$ bpkg install your-username/your-repo -g

6.2. Local Usage:

After installation, you should be able to use the installed command locally.
Example:

• If your package includes a command named your-command, you should be able to run it in the terminal:

$ your-command [options] [arguments]

7. Additional Tips

• Versioning:
  • Consider versioning your package using Semantic Versioning.
• Licensing:
  • Add a LICENSE file to clearly state how others can use, modify, and distribute your package.