بسم الله الرحمن الرحيم

Pkg 📦 - A package manager

[!CAUTION] please read this README carefully before use + read the Bridges section CAUTION wrotten there becuase maybe if u don't understand what's wrotten here correctly ur gonna make big security mistakes.

Pkg is a powerful insh'Allah, multi-language-secriptable, multi-platform, multi-repo yet simple and declarative package manager. In other sed u can insah'Allah insatll packages via pkg from any where insha'Allah in sync with a config files via simple scripts that wrotten in any language on any unix-like machine insha'Allah.

[!IMPORTANT] the program can contain bugs and it's required running as root, NO WARRANTYS, use at your own risks.

Demo

Features

• 📦 Install packages from any repo
• 💻 Platform undependent (works insha'Allah on any unix-like machine)
• 🧱 written in rust (fast, portable yet simple insha'Allah)
• 📝 declarative all ur packages are wrtten in files (u have on ur machine what u have in the config files insha'Allah)
• 🚚 multi-repo support (u can write a simple script (bridge) to install from any where insha'Allah)
• 🗃️ full-management of packages insha'Allah install, update, remove support

Installation

Note

this program is unix only (linux, mac, bsd*, etc.)

Install from crates.io

cargo install pkg-rs # the name pkg is token

From releases

1. go to releases and download the latest release for your system.
2. move it to /usr/local/bin

From source

cargo install --git https://github.com/abdelkadous/pkg.git --root .

if you don't wanna shell completion disable the feature cli_complation by adding this flag: --no-default-features

Usage

there is some consepts that u need to know before using pkg:

1. a bridge is a simple script that u can write to support declare new way to install packages from any where insha'Allah.
2. an input is the file where u write the packages that u want to install.
3. a pkg here is two types:
   1. a Single Executable this is the pkg just is a one binary u can run insah'Allah
   2. a Directory a pkg that is a directory that contains one then one file can be for e.g runtimes, libs, man pages, helper files, anthoer executable... but this type of pkg should have an entry point which a executable file to run the app from (pkg gonna link this file in PATH insha'Allah).

onec u know that let's dive into the usage process:

in the name of Allah:

1. Config pkg

the config is in kdl in this path: ~/.config/pkg/.config this is a config example with explanations:

config {
  inputs { // here u declare the inputs of the program options
    path "~/.config/pkg" // where the program can find the inputs (the files where u write ur packages) insha'Allah
    bridges-set "~/.config/pkg/.bridges" // where the program can find the bridges (the install scripts) insha'Allah
  }
  output { // where the program write the outputs
    target-dir "/opt/pkg" // the dir where u wanna pkg to install the packages
    load-path "/usr/local/pkg" // this path is the only path that u have to add to PATH insha'Allah. which is a dir where pkg gonna make all the symlinks to the pkg (pkg entry points)
  }
  db {
    path "/var/db/pkg/packages.db" // pkg db path (a sqlite db that pkg used to store the packages info)
  }
}

[!TIP] this is the recommended config file so we highly recommend to just copy and paste this. There is no default config u have to write this file or the program wont work insha'Allah

2. Add the bridges

the bridges as i said before is just scripts that contain the logic to install packages from any where insha'Allah.

u can write ur own bridges and for that read the bridges section to know the the rools insha'Allah but as bigging we recommend to start with using me bridges that u can find as my dotfiles at here. Just featch them and put them in the path input.bridges-set in the config file. And make sure to read the READMEs.

3. Add the inputs

finally u can add some pkgs to install. for e.g if u using my bridges u can add this write a file in the path u set as input.path in the config file called test.kdl then add this in the file:

cargo { // cargo is the bridge name that u wanna use to install the packages inside the curly bracts
    bat "bat" // this is the first package for e.g, it's good to add a description to the pkg like so
    // NOTE: u see the pkg node is two parts, the first is the executable name (pkg gonna store the pkg executable after install with this name so u can reaname it BTW), the secand is called the input which what to pass to the bridge.
    // HACK: where the name == input u can use a shortcut by just writing the name, e.g: bat
    zoxide // like this
    // BUG: don't use the input shortcut if u have options (see #3)
}

eget { // this is another bridge to install from github, direct urls
    gh "cli/cli" // github cli
  nvim "neovim/neovim" keep_structure=#true target="*" entry_point="bin/nvim" // this is how to install nvim for e.g
    // NOTE: the extra args called options and it's gonna be passed to the bridge as env vars
}

4. Run pkg

Now u can install the packages by running pkg:

pkg build # or sync (sync == build)

now try remove the packages:

1. go ahead and remove any one from the inputs e.g:

// test.kdl
cargo {
-   bat "bat" // ...
+   bat "bat" // ...
    ...
}

2. rerun the same command now:

pkg build # or sync

3. try using the command now (if u don't have it installed in anthoer place before alredy)

bat --version # the shll sould return error command not found

now try update the packages:

for all the pkgs just run:

pkg update

or for a specific pkg:

pkg update <the-pkg-name> # e.g: pkg update nvim

5. Full Example

for a full real example see the examples dir in my dotfiles repo.

Bridges

[!CAUTION] bridges are just scripts in the end of the day and can contain bugs but the problem with bridge is that it's so dangerous becuase it's running as root in ur computer becuase of pkg management purpose so make sure u are know what inside this bridge and make sure to well test it before use. we recommended to dev this bridges inside a container. for e.g use docker.

How to write a bridge ( how the bridges works )

a bridge is a dir in the path input.bridges-set in the config file. the dir should contain a file called run with the executable permistion, to make one run:

mkdir <path/to/bridges-set-dir>/test
touch <path/to/bridges-set-dir>/test/run
chmod +x <path/to/bridges-set-dir>/test/run

the run file should handle two args:

1. operation: string: install, update, remove
2. input: string: the string that u write after the pkg name in the inputs files, the inputs passed here one by one insha'Allah.

pkg gonna run ur bridges like this:

<path/to/bridges-set-dir>/test/run install <input> # or update, remove

u just have to handle one of the valid operations as must wich is the install operation. insha'Allah. but the other operations have a default implemention that u can use. To know how to use the default implemention and more info run the pkg docs command.

example of a bridge:

file tree:

// under the bridges-set dir
test_bridge
├── run
└── install_command_handler.sh

run:

#!/usr/bin/env bash

if [ "$1" == "install" ]; then
    ./install_command_handler.sh $2
else
    echo "__IMPL_DEFAULT" # tell pkg to use the default implemention
    exit 1 # it's should exit with 1 to let pkg know that he have to use the default implemention and this is not an unhanled error.
fi

install_command_handler.sh:

#!/usr/bin/env bash
echo 'this pkg should be' $1 > pkg
echo './pkg,0.0.1' # then u have to return the pkg path then comma then the pkg version. if this pkg type is dir so return pkg dir path then comma the version then comma then pkg executable (entry point). run pkg docs for more info.

Known Issues

1. don't use the input shortcut if u have options (see [#3]) e.g:

bridge {
-   pkg opt1=val1 opt2=val2 opt3=val3 # ❌ this is wrong
+   pkg "pkg" opt1=val1 opt2=val2 opt3=val3 # ✅ this is fine insha'Allah
}

2. pkg has more then one executable but all of them should be linked in the PATH: pkg mainly new support pkg has more then one executable but it's just link one on the PATH.

Debugging

U may get fails in ur installs with brigets to debug them check the log files on: /var/log/pkg/<bridge-name>.log

[!TIP] run pkg clean from time to time to clean the logs and the installs garbage.

Contributing

the project is open to contributions, if u want to contribute open an issue or a pr.

FAQ

1. Why shell completion is a feature?

   in my opinion u should't store static data in bin formae specially if u need this data only onec, u probably gonna run this command onec so why to store is the bin this is an overhead.

2. Why bridges are just an executable files what to do not add a scripting engine for better integration:

   look at issue [#2], and a short answer is this project was support lua before, but this change, and this is better for muli language support and a lot of stuff.

License

Pkg is licensed under the GNU General Public License v3.0 plus one extra condition:

• Your use should be in line with the Islamic Sharia Laws. If there is any conflict between the terms of the 'GNU General Public License v3.0' and the Islamic Sharia Laws, the Islamic Sharia Laws shall prevail.