commit 8a833d7a0c5994f0a256ea3f2b729a92162ba8af
parent 0f68bd29fd9c6c2f623463137d5fe1e9137bc7a8
Author: phoebos <ben@bvnf.space>
Date: Fri, 26 Apr 2024 15:48:09 +0100
more documentation
Diffstat:
9 files changed, 92 insertions(+), 19 deletions(-)
diff --git a/bliss/archive.lua b/bliss/archive.lua
@@ -1,9 +1,12 @@
+--- Tarball creation and extraction.
+-- @module bliss.archive
local utils = require "bliss.utils"
local dirent = require "posix.dirent"
local stdio = require "posix.stdio"
local unistd = require "posix.unistd"
--- extracts tarball to PWD
+--- Extract a tarball to PWD.
+-- @tparam string tarball filename of tarball
local function tar_extract(tarball)
if not utils.run("tar", {"xf", tarball}) then
utils.die("failed to extract "..tarball)
@@ -26,7 +29,9 @@ local function tar_extract(tarball)
end
end
--- p is a package table as in bliss.build
+--- Create a tarball.
+-- @tparam env env
+-- @tparam ppkg p as in the format used in bliss.build
local function tar_create(env, p)
utils.log(p.pkg, "Creating tarball")
unistd.chdir(env.pkg_dir .. "/" .. p.pkg)
@@ -49,6 +54,7 @@ local function tar_create(env, p)
utils.log(p.pkg, "Successfully created tarball")
end
+--- @export
local M = {
tar_extract = tar_extract,
tar_create = tar_create,
diff --git a/bliss/build.lua b/bliss/build.lua
@@ -1,3 +1,5 @@
+--- Package building.
+-- @module bliss.build
local utils = require "bliss.utils"
local archive = require "bliss.archive"
local pkg = require "bliss.pkg"
@@ -8,17 +10,26 @@ local libgen = require "posix.libgen"
local sys_stat = require "posix.sys.stat"
local unistd = require "posix.unistd"
---[[
--- These functions use a table containing cached package variables:
--- p = {
--- pkg,
--- repo_dir,
--- sources,
--- caches,
--- ver,
--- rel,
--- }
---]]
+
+--- @table ppkg
+-- Many functions use a table containing these cached package variables:
+-- @field pkg package name
+-- @field repo_dir package directory
+-- @field sources list of sources
+-- @field caches list of caches
+-- @field ver package version
+-- @field rel package release
+
+local function new_ppkg(p, repo_dir, sources, caches, ver, rel)
+ return {
+ pkg = p,
+ repo_dir = repo_dir,
+ sources = sources,
+ caches = caches,
+ ver = ver,
+ rel = rel
+ }
+end
local function build_extract(env, p)
if #p.caches == 0 then return end
@@ -154,6 +165,10 @@ local function gen_etcsums(env, p)
etcsums:close()
end
+
+--- The build action.
+-- @tparam env env
+-- @tparam table arg list of explicit packages to build
local function build(env, arg)
if #arg == 0 then end -- TODO
@@ -209,7 +224,7 @@ local function build(env, arg)
download.download_sources(env, p, sources, caches)
checksum.verify_checksums(p, repo_dir, caches)
- table.insert(db, {pkg = p, repo_dir = repo_dir, sources = sources, caches = caches, ver = version[1], rel = version[2]})
+ table.insert(db, new_ppkg(p, repo_dir, sources, caches, version[1], version[2]))
end
-- Now build
@@ -231,6 +246,7 @@ local function build(env, arg)
end
end
+--- @export
local M = {
build = build,
}
diff --git a/bliss/checksum.lua b/bliss/checksum.lua
@@ -1,9 +1,13 @@
+--- Checksum routines.
+-- @module bliss.checksum
local utils = require "bliss.utils"
local b3sum = require "bliss.b3sum"
local pkg = require "bliss.pkg"
local download = require "bliss.download"
--- returns a string of the BLAKE3 checksum of the contents of filename
+--- Get the checksum of a single file.
+-- @tparam string filename
+-- @treturn string the BLAKE3 checksum of the contents of filename
local function checksum_file(filename)
local f = assert(io.open(filename))
local ctx = b3sum.init()
@@ -16,6 +20,10 @@ local function checksum_file(filename)
return b3sum.finalize(ctx, 33)
end
+--- The checksum action.
+-- Generates checksums for all the packages.
+-- @tparam env env
+-- @tparam table arg list of packages
local function checksum(env, arg)
if #arg == 0 then utils.die("need a package") end
for _,p in ipairs(arg) do
@@ -46,6 +54,10 @@ local function checksum(env, arg)
end
end
+--- Verify all the checksums for a package
+-- @tparam string p package name
+-- @tparam string repo_dir package directory
+-- @tparam table caches list of downloaded files to checksum
local function verify_checksums(p, repo_dir, caches)
utils.log(p, "Verifying sources")
@@ -61,6 +73,7 @@ local function verify_checksums(p, repo_dir, caches)
end
end
+--- @export
local M = {
checksum = checksum,
checksum_file = checksum_file,
diff --git a/bliss/download.lua b/bliss/download.lua
@@ -1,3 +1,5 @@
+--- Downloading routines.
+-- @module bliss.download
local utils = require "bliss.utils"
local pkg = require "bliss.pkg"
local sys_stat = require "posix.sys.stat"
@@ -44,7 +46,12 @@ local function file(env, p, source, dest)
end
end
--- download each source to dest.
+--- Download each source to dest.
+-- Currently handles http, git, and local files.
+-- @tparam env env
+-- @tparam string p package name (just used as a label for log messages)
+-- @tparam table sources list of sources
+-- @tparam table dests list of destinations
local function download_sources(env, p, sources, dests)
assert(#dests == #sources)
@@ -56,7 +63,9 @@ local function download_sources(env, p, sources, dests)
end
end
--- this is the download action (ie. kiss d)
+--- The download action.
+-- @tparam env env
+-- @tparam table arg list of packages to download sources for
local function download(env, arg)
if #arg == 0 then return end -- TODO
@@ -73,6 +82,7 @@ local function download(env, arg)
end
end
+--- @export
local M = {
download = download,
download_sources = download_sources,
diff --git a/bliss/install.lua b/bliss/install.lua
@@ -1,9 +1,14 @@
+--- Install a built package.
+-- @module bliss.install
local archive = require "bliss.archive"
local utils = require "bliss.utils"
local pkg = require "bliss.pkg"
local libgen = require "posix.libgen"
local sys_stat = require "posix.sys.stat"
+--- The install action.
+-- @tparam env env
+-- @tparam table arg
local function install(env, arg)
if #arg == 0 then end
@@ -94,6 +99,7 @@ local function install(env, arg)
end
end
+--- @export
local M = {
install = install,
}
diff --git a/bliss/list.lua b/bliss/list.lua
@@ -1,6 +1,11 @@
+--- List packages.
+-- @module bliss.list
local pkg = require "bliss.pkg"
local dirent = require "posix.dirent"
+--- The list action.
+-- @tparam env env
+-- @tparam table arg list of packages to search. If none, list all packages.
local function list(env, arg)
if #arg == 0 then
for file in dirent.files(env.sys_db) do
@@ -18,6 +23,7 @@ local function list(env, arg)
end
end
+--- @export
local M = {
list = list,
}
diff --git a/bliss/search.lua b/bliss/search.lua
@@ -1,7 +1,12 @@
+--- Package searching.
+-- @module bliss.search
local utils = require "bliss.utils"
local glob = require "posix.glob"
local sys_stat = require "posix.sys.stat"
+--- The search action.
+-- @tparam env env
+-- @tparam table arg list of search queries
local function search(env, arg)
-- append sys_db to search path
@@ -30,6 +35,7 @@ local function search(env, arg)
end
end
+--- @export
local M = {
search = search,
}
diff --git a/bliss/tsort.lua b/bliss/tsort.lua
@@ -1,4 +1,8 @@
+--- Topological sorting.
-- This module is not included in init.lua, but used locally by pkg.lua.
+-- @module bliss.tsort
+
+--- @type tsort
local tsort = {}
-- Returns a table of reverse deps
@@ -26,16 +30,21 @@ local function find_cycle(revlinks, start)
return t, old
end
+--- Get a new tsort object.
+-- @treturn tsort
function tsort.new()
return setmetatable({nodes={}}, {__index = tsort})
end
--- deps is an array of ALL the deps for node. Calling add for the same node a
--- second time overwrites, not appends.
+--- Add a node.
+-- @tparam string node
+-- @tparam table deps array of all the deps for node. Calling add for the same node a second time overwrites, not appends.
function tsort:add(node, deps)
self.nodes[node] = deps
end
+--- Sort the nodes.
+-- @treturn table sorted array of nodes
function tsort:sort()
if not self.nodes then return nil end
local L = {}
diff --git a/config.ld b/config.ld
@@ -3,6 +3,7 @@ project = "bliss 0.0.0"
title = "bliss 0.0.0 reference"
description = "kiss in Lua"
+not_luadoc = true
output = "doc"
sort = true
readme = "README.md"
