diff options
| -rw-r--r-- | config/init.lua | 247 | ||||
| -rw-r--r-- | docs/pkgit.1 | 188 |
2 files changed, 435 insertions, 0 deletions
diff --git a/config/init.lua b/config/init.lua new file mode 100644 index 0000000..0557a89 --- /dev/null +++ b/config/init.lua @@ -0,0 +1,247 @@ +--[[ introduction + + this is the pkgit configuration template. + every configuration file is written in lua, + the embeddable high-level programming language. + + for info on how to write lua, check out + this website for documentation: + https://www.lua.org/pil/contents.html + + all variables that are + set by default are designed to + work out of the box. be sure to + keep the global variables global, + as they need to be global in + order for them to work with + each other effectively. + + `local install_directories`, for + example, will not work well in + most cases. + +]] + +--[[ prefix + + the prefix variable is necessary + for custom install paths, which + bldit maintainers should be + respecting with their recipes. + + if you want to install packages + without root, it's easist to + create a home variable and + append that to your prefix. + +]] +local home = os.getenv("HOME") +prefix = home.."/.local" + +--[[ install_directories + + install_directories is an essential + table that pkgit needs in order to + function. this is how it determines + where you install your packages to. + + it's most convenient when combined + with `prefix` which allows for a + more dynamic definition of your + install directories. + +]] +install_directories = { + bin = prefix.."/bin", -- binaries (executables) + -- the value of `bin` should also be set in your shell's $PATH + include = prefix.."/include", -- C headers + lib = prefix.."/lib", -- libraries (shared objects) + src = prefix.."/share/pkgit", -- source code +} + +--[[ repositories + + this is where all your repos need to + end up. every repo has a name, which + can be written out normally + (`name = {...}`), or for some repos, + it might be necessary to wrap it in + quotes (`["name"] = {...}`). + that name can be used in a pkgit + command to be installed. + ( `pkgit --install [repo]` ) + + each of these repos must be structured + as a lua table. the structure is + demonstrated below. + +]] +repositories = { + pkgit = { + url = "https://git.symlinx.net/pkgit", + --[[ repo example + + no targets table or dependencies are actually needed in + this specific case, pkgit has a bldit.lua which guarantees + that it will compile & install (as long as `install_directories` + and `prefix` are set up). + + if you do make a targets table here, it will take priority + over the bldit.lua in the repo, and your build system + autodetection config ( `build_systems = {...}` ) + + more about `targets` in the global `build_systems` table. + + ]] + --dependencies = { + -- name = { + -- url = {...}, + -- version = "...", + -- target = "...", + -- }, + --}, + --targets = { + -- default = { + -- build = function() + -- return os.execute("make") + -- + -- -- ^ make sure to return the exit code of os.execute ^ -- + -- + -- end, + -- install = function() + -- return os.execute("make install PREFIX="..prefix) + -- end, + -- uninstall = function() + -- return os.execute("make uninstall PREFIX="..prefix) + -- end, + -- } + --} + }, +} + +--[[ build_systems + + this table contains all of the automatic + build system detection necessary for pkgit + to work without bldit.lua or `repositories = {...}`. + + this works by creating a table named after the + filename associated with the build system that + is found in the root directory of a package. + + by associating a filename with a build system, + pkgit can dynamically compile and install any + package, given that they use the build system + according to the standard (or otherwise + generally popular) usage guidelines. + +]] +build_systems = { + ["Makefile"] = { + --[[ targets + + briefly mentioned above in `repositories`, + the `targets` subtable is a standard that's + consistent across all the different methods + to build a package using pkgit; meaning + you can write the same `targets` subtable + in `repositories.<pkg>`, `bldit.lua`, and + right here in `build_systems`. + + this table comes with two templates; + `default` and `quiet`. the first is pretty + self-explanatory; this is what you'd define + as the default intended behavior of the + build system. + + `quiet` is similar to `default`, in the sense + that it inherits the default intended behavior, + except that it does so while printing nothing + to the terminal. instead, ideally, it would + output its logs to a temporary file accessible + by the user running the command. + + this is why the default logs in this example + are located in `/tmp` and not `/var/log`, + because the user typically has full access to + `/tmp`, and normally not `/var/log`. + + ]] + targets = { + default = { + build = function() + return os.execute("make") + end, + install = function() + return os.execute("make install PREFIX="..prefix) + end, + uninstall = function() + return os.execute("make uninstall PREFIX="..prefix) + end, + }, + quiet = { + build = function() + return os.execute("make &>/tmp/pkgit_build.log") + end, + install = function() + return os.execute("make install PREFIX="..prefix.." &>/tmp/pkgit_build.log") + end, + uninstall = function() + return os.execute("make uninstall PREFIX="..prefix.." &>/tmp/pkgit_build.log") + end, + }, + } + }, + ["meson.build"] = { + targets = { + default = { + build = function() + return os.execute("meson setup build --prefix "..prefix.." && meson compile -C build") + end, + install = function() + return os.execute("cd build && meson install") + end, + uninstall = function() + return os.execute("cd build && ninja uninstall") + end, + }, + quiet = { + build = function() + return os.execute("meson setup build --prefix "..prefix.." &>/tmp/pkgit_build.log && meson compile -C build &>/tmp/pkgit_build.log") + end, + install = function() + return os.execute("cd build && meson install &>/tmp/pkgit_build.log") + end, + uninstall = function() + return os.execute("cd build && ninja uninstall &>/tmp/pkgit_build.log") + end, + }, + } + }, + ["CMakeLists.txt"] = { + targets = { + default = { + build = function() + return os.execute("cmake -B build && cmake --build build") + end, + install = function() + return os.execute("cmake --build . --target install") + end, + uninstall = function() + return os.execute("xargs rm < install_manifest.txt") + end, + }, + quiet = { + build = function() + return os.execute("cmake -B build &>/tmp/pkgit_build.log && cmake --build build &>/tmp/pkgit_build.log") + end, + install = function() + return os.execute("cmake --build . --target install &>/tmp/pkgit_build.log") + end, + uninstall = function() + return os.execute("xargs rm < install_manifest.txt &>/tmp/pkgit_build.log") + end, + }, + } + }, +} diff --git a/docs/pkgit.1 b/docs/pkgit.1 new file mode 100644 index 0000000..4606acd --- /dev/null +++ b/docs/pkgit.1 @@ -0,0 +1,188 @@ +.TH PKGIT 1 "2026-06-22" "git.symlinx.net/pkgit" "User Commands" +.SH NAME +pkgit \- an unconventional package manager +.SH SYNOPSIS +.B pkgit +.RI [ options ] " " <package> +.br +.B pkgit +.RI [ options ] " " <command> " " [arguments] +.SH DESCRIPTION +.B pkgit +is an unconventional package manager designed to compile and install packages directly from their git repository. +.PP +Commands in +.B pkgit +follow a standard structure: +.PP +.RS +.B pkgit +.RI [ \-\-flag | \-f ] " " <package> +.RE +.PP +Flags have two forms: long (e.g., \fB\-\-install\fR) and short (e.g., \fB\-i\fR). +The short form uses the first letter of the long counterpart. Short flags +can be chained together into a single argument. For example, +.B \-qif +combines +.BR \-\-quiet , +.BR \-\-install , +and +.BR \-\-force . +.SH WARNING +Due to the nature of +.BR pkgit , +you are solely responsible for vetting the repositories that you add to your system. Use at your own risk. +.SH COMPILATION +To compile +.B pkgit +from source, enter the project directory and run one of the following: +.PP +.RS +.B make +.RE +or +.RS +.B pkgit \-\-build +.RE +.PP +Both methods will create an executable in the root directory of the project. +.PP +You may also want to generate a base configuration file. Run the following as a regular user to generate the config in +.IR ~/.config/pkgit : +.PP +.RS +.B make defconfig +.RE +.PP +Alternatively, run as root (using +.B sudo +or +.BR doas ) +to generate the system-wide config in +.IR /etc/pkgit : +.PP +.RS +.B sudo make defconfig +.RE +.SH INSTALLATION +After compiling, install the package with root privileges: +.PP +.RS +.B make install +.RE +.PP +If you do not have root privileges, or prefer a local installation, you can specify an install location using the +.B PREFIX +variable. A common choice is +.IR ~/.local : +.PP +.RS +.B make install PREFIX="~/.local" +.RE +.SH ENVIRONMENT +Before using programs installed via +.BR pkgit , +ensure the binary path is added to your shell's +.BR PATH . +For a local installation (e.g., +.IR ~/.local/bin ), +add the following to your shell configuration: +.PP +.TP +.B Bash / Zsh +export PATH="$HOME/.local/bin:$PATH" +.TP +.B Fish +fish_add_path $HOME/.local/bin +.TP +.B Csh / Tcsh +setenv PATH $HOME/.local/bin:$PATH +.SH OPTIONS +These options modify the behavior of commands. +.TP +.BR \-q ", " \-\-quiet +Minimize logs output to stdout. +.TP +.BR \-f ", " \-\-force +Force the package to be installed, even if it is already installed. +.SH COMMANDS +.TP +.BR \-i ", " \-\-install " \fI<target>\fR" +Install a package. Assuming the respective repository has been added, +you can specify the package by name. The \fI<target>\fR argument supports +several syntax variations: +.RS +.TP +.B Basic install +.B pkgit \-\-install +.I pkg_name +.TP +.B Specific version +.B pkgit \-\-install +.IR pkg_name @ version +.TP +.B Specific target +.B pkgit \-\-install +.IR pkg_name , target +(Target is based on configuration in +.I bldit.lua +or +.IR init.lua ). +.TP +.B Combined target and version +.B pkgit \-\-install +.IR pkg_name , target @ version +or +.B pkgit \-\-install +.IR pkg_name @ version , target +(Order does not matter as long as the package name is first). +.TP +.B Repo install +.B pkgit \-\-install +.I url.git +(Installs directly from a git URL. Works with target and version syntax). +.TP +.B Local install +.B pkgit \-\-install " ." +(Installs from the local code repository in the current directory, +taking advantage of pkgit's build system autodetection). +.RE +.TP +.BR \-b ", " \-\-build " \fI[/path/to/project]\fR" +(Best for developers) Act as a meta-build-system to automatically compile +any supported project. Can be run from the project's root directory +without specifying the path. +.TP +.BR \-r ", " \-\-remove " \fI<pkg_name>\fR" +Remove (uninstall) an installed package. +.TP +.BR \-u ", " \-\-update +Update all installed packages. +.TP +.BR \-d ", " \-\-declare +Use the configuration file as a package declaration file to declare +and install all packages at once. +.SH EXAMPLES +.TP +Install a package quietly, forcing the installation: +.B pkgit \-qif +.I mypackage +.TP +Install a specific version and target of a package: +.B pkgit \-i +.I mypackage,mytarget@1.0.0 +.TP +Install a package directly from a git repository: +.B pkgit \-\-install +.I https://github.com/heather7283/pipemixer +.TP +Build the project in the current directory: +.B pkgit \-\-build +.SH SEE ALSO +.BR git (1), +.BR lua (1) +.SH AUTHORS +.B pkgit +is developed and maintained by the contributors at +.IR git.symlinx.net/pkgit .)' |