checkpoint!

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 .)'