dymokomi/luc
Source of release 0.24.0
## Applications: `luc install owner/name` fetches the source, builds it, and installs
## what the package's install script asks for into ~/.luce/apps/<name>/<version>/.
##
## The script is high-level Luce run with `luce run --sandbox`, so it has no file,
## network or process access. It receives `<os> <arch> <name> <version>` and prints a
## plan, one instruction a line:
## copy <path-in-package> -> <path-in-install-directory>
## link <command-name> -> <path-in-install-directory>
## luc validates every path and does the copying. A package without a script gets
## the default: its built executable as bin/<name>, linked as <name>.
import c
from luce_std import files
import memory
import os
from luce_std import paths, process
import strings
from luce_pkg import pkg
pub let invalid = pkg.invalid
let max_plan_lines: usize = 1024
func ensure_directory(path: str) -> !:
let terminated = try strings.copy(path)
defer strings.release(terminated)
if not files.exists((c.str)terminated): try files.create_directory((c.str)terminated)
## `left` and `right` joined, as text the caller releases with strings.release.
func join(left: str, right: str) -> str!:
let joined = try paths.join(left, right)
defer joined.release()
return try strings.copy(joined.value)
func exists(path: str) -> bool!:
let terminated = try strings.copy(path)
defer strings.release(terminated)
return files.exists((c.str)terminated)
## ~/.luce (or LUC_HOME), created as needed.
pub func home() -> str!:
if let chosen = os.env((c.str)"LUC_HOME"):
try ensure_directory(chosen)
return try strings.copy(chosen)
let user = try user_home()
defer strings.release(user)
let directory = try join(user, ".luce")
errdefer strings.release(directory)
try ensure_directory(directory)
return directory
## LUC_HOME when it names a place other than the default ~/.luce: what a command run from
## another shell, which may not have it set, must be told. None for the default.
pub func chosen_home() -> str?!:
let chosen = os.env((c.str)"LUC_HOME") else return none
if chosen.length == 0:
return none
let user = user_home() catch:
return try strings.copy(chosen)
defer strings.release(user)
let default = try join(user, ".luce")
defer strings.release(default)
if chosen == default:
return none
return try strings.copy(chosen)
pub func child(parent: str, name: str) -> str!:
let directory = try join(parent, name)
errdefer strings.release(directory)
try ensure_directory(directory)
return directory
## Relative, `/`-separated, no empty, `.` or `..` segment, backslash, colon or control byte.
func path_valid(value: str) -> bool:
if value.length == 0 or value.length > 1024: return false
var start: usize
for end in 0..<value.length + 1:
if end != value.length:
let byte = value.bytes[end]
if byte < 0x20 or byte == 0x7f or byte == '\\' or byte == ':': return false
if byte != '/': continue
let part = (str)value.bytes[start..<end]
if part.length == 0 or part == "." or part == "..": return false
start = end + 1
return true
func command_valid(value: str) -> bool:
if value.length == 0 or value.length > 64: return false
for i in 0..<value.length:
let byte = value.bytes[i]
let alnum = (byte >= 'a' and byte <= 'z') or (byte >= '0' and byte <= '9')
if not alnum and (i == 0 or (byte != '_' and byte != '-')): return false
return true
## Copy a regular file or a whole directory tree. Symlinks and special files are refused,
## so nothing in a package can make the copy reach outside it.
func copy_tree(source: str, destination: str, budget: usize*) -> !:
if *budget == 0: error(invalid, "an install copies too many files")
*budget -= 1
let origin = try strings.copy(source)
defer strings.release(origin)
let target = try strings.copy(destination)
defer strings.release(target)
let info = try files.metadata((c.str)origin, follow_symlinks = false)
if info.kind == files.FileKind.regular:
_ = try files.copy_file((c.str)origin, (c.str)target, permissions = info.permissions & 0o777)
return
if info.kind != files.FileKind.directory: error(invalid, "an install may copy only regular files and directories")
try files.create_directory((c.str)target)
let names = try files.list((c.str)origin)
defer names.release()
for name in names.value:
let inner_source = try paths.join(source, name)
defer inner_source.release()
let inner_destination = try paths.join(destination, name)
defer inner_destination.release()
try copy_tree(inner_source.value, inner_destination.value, budget)
## Create the parent directories of a relative path below `root`.
func ensure_parents(root: str, relative: str) -> !:
var current = try strings.copy(root)
defer strings.release(current)
var start: usize
for end in 0..<relative.length:
if relative.bytes[end] != '/': continue
let next = try join(current, (str)relative.bytes[start..<end])
strings.release(current)
current = next
try ensure_directory(current)
start = end + 1
## Split `verb left -> right`. Paths may contain spaces, so only the arrow separates them.
func instruction(line: str) -> (str, str, str)!:
let (verb, rest) = strings.split_once(line, " ") else error(invalid, "an install plan line is `copy A -> B` or `link NAME -> B`")
let (left, right) = strings.split_once(rest, " -> ") else error(invalid, "an install plan line is `copy A -> B` or `link NAME -> B`")
return (verb, strings.trim(left), strings.trim(right))
func release_arguments(arguments: c.str[], filled: usize*):
for i in 0..<*filled: strings.release((str)arguments[i])
## Run the package's install script in the sandbox and return its plan. The caller
## releases it with strings.release.
pub func scripted_plan(luce: str, package_root: str, script: str, name: str, version: str) -> str!:
let program = try strings.copy(luce)
defer strings.release(program)
let script_path = try paths.join(package_root, script)
defer script_path.release()
let system = "macos" if os.macos else ("linux" if os.linux else "windows")
let machine = "arm64" if os.arm64 else "x86_64"
let words = ["run", "--sandbox", package_root, script_path.value, "--", system, machine, name, version]
let argv = try new c.str[words.length] --- in memory.heap
defer free(argv) in memory.heap
var filled: usize
defer release_arguments(argv, &filled)
while filled < words.length:
argv[filled] = (c.str)try strings.copy(words[filled])
filled += 1
let ran = try process.run((c.str)program, argv)
defer ran.release()
if ran.value.exit_code != 0:
error(invalid, "the install script failed or the sandbox is unavailable on this system")
return try strings.copy(ran.value.output)
## Apply a plan: copies into `staging`, then the command links it declares into `links`
## (one `name<TAB>relative-target` line each), which the caller turns into ~/.luce/bin entries.
pub func apply(plan: str, package_root: str, staging: str, links: u8[], links_used: usize*) -> !:
var budget: usize = 20000
var count: usize
var start: usize
for end in 0..<plan.length + 1:
if end != plan.length and plan.bytes[end] != '\n': continue
let line = strings.trim((str)plan.bytes[start..<end])
start = end + 1
if line.length == 0 or line.bytes[0] == '#': continue
count += 1
if count > max_plan_lines: error(invalid, "the install plan is too long")
let (verb, first, second) = try instruction(line)
if verb == "copy":
if not path_valid(first) or not path_valid(second): error(invalid, "an install plan path must be relative and stay inside its directory")
let source = try paths.join(package_root, first)
defer source.release()
let destination = try paths.join(staging, second)
defer destination.release()
if try exists(destination.value): error(invalid, "an install plan writes the same path twice")
try ensure_parents(staging, second)
try copy_tree(source.value, destination.value, &budget)
elif verb == "link":
if not command_valid(first) or not path_valid(second): error(invalid, "an install plan link needs a command name and a relative path")
let needed = first.length + second.length + 2
if *links_used + needed > links.length: error(invalid, "the install plan declares too many links")
for byte in first.bytes:
links[*links_used] = byte
*links_used += 1
links[*links_used] = '\t'
*links_used += 1
for byte in second.bytes:
links[*links_used] = byte
*links_used += 1
links[*links_used] = '\n'
*links_used += 1
else:
error(invalid, "an install plan line must start with copy or link")
if count == 0: error(invalid, "the install plan is empty")
# mark: Commands ===============================================================================
## Make `command` in `commands` start `target`: a symbolic link, or on Windows, where a link
## needs Developer Mode or an administrator, a `command.cmd` that runs it with its arguments.
pub func link_command(commands: str, command: str, target: str) -> !:
let link = try command_path(commands, command)
defer strings.release(link)
let link_z = try strings.copy(link)
defer strings.release(link_z)
_ = files.remove_file((c.str)link_z) catch: recover ()
if os.windows:
var native = try strings.copy(target)
defer strings.release(native)
let bytes = (u8[])native.bytes
for i in 0..<bytes.length:
if bytes[i] == '/': bytes[i] = '\\'
let text = try new u8[native.length + 32] --- in memory.heap
defer free(text) in memory.heap
try write_text(link, try strings.format(text, f"@\"{native}\" %*\r\n"))
return
let target_z = try strings.copy(target)
defer strings.release(target_z)
try files.create_symlink((c.str)target_z, (c.str)link_z)
## Remove what link_command made for `command`: the link, or the Windows `.cmd`. Anything
## else of that name is not luc's and stays.
pub func unlink_command(commands: str, command: str) -> !:
let link = try command_path(commands, command)
defer strings.release(link)
let link_z = try strings.copy(link)
defer strings.release(link_z)
if os.windows:
if files.exists((c.str)link_z): try files.remove_file((c.str)link_z)
return
# Only a link is removed; anything else of that name stays.
let linked = files.read_symlink((c.str)link_z) catch: return
linked.release()
try files.remove_file((c.str)link_z)
func command_path(commands: str, command: str) -> str!:
if not os.windows:
return try join(commands, command)
var name: u8[96]
return try join(commands, try strings.format(name, f"{command}.cmd"))
# mark: Desktop bundles ========================================================================
func write_text(path: str, text: str) -> !:
let terminated = try strings.copy(path)
defer strings.release(terminated)
try files.write((c.str)terminated, text.bytes)
func copy_into(source: str, directory: str, name: str, permissions: u32) -> !:
let destination = try paths.join(directory, name)
defer destination.release()
let origin = try strings.copy(source)
defer strings.release(origin)
_ = try files.copy_file((c.str)origin, (c.str)destination.value, permissions = permissions)
func fresh_directory(path: str) -> !:
let terminated = try strings.copy(path)
defer strings.release(terminated)
if files.exists((c.str)terminated): try files.remove_tree((c.str)terminated)
try files.create_directory((c.str)terminated)
## The bundle directory name inside build/: "Name.app" on macOS, "Name.AppDir" on Linux,
## and on Windows the program folder "Name" that holds name.exe.
pub func bundle_name(definition: pkg.Definition*, output: u8[]) -> str!:
if os.macos: return try strings.format(output, f"{definition.application.name}.app")
if os.linux: return try strings.format(output, f"{definition.application.name}.AppDir")
return try strings.format(output, f"{definition.application.name}")
## Wrap the built executable build/<name> as a desktop application, so it opens as an
## application rather than in a terminal.
pub func bundle(root: str, definition: pkg.Definition*) -> !:
var name_buffer: u8[96]
let directory_name = try bundle_name(definition, name_buffer)
let build = try paths.join(root, "build")
defer build.release()
var executable_name: u8[128]
let built_name = try strings.format(executable_name, f"{definition.name}.exe") if os.windows else definition.name
let executable = try paths.join(build.value, built_name)
defer executable.release()
let bundle_root = try paths.join(build.value, directory_name)
defer bundle_root.release()
try fresh_directory(bundle_root.value)
var icon_name = ""
if definition.application.icon.length > 0: icon_name = paths.base(definition.application.icon)
let icon_source = try paths.join(root, definition.application.icon)
defer icon_source.release()
let text = try new u8[8192] --- in memory.heap
defer free(text) in memory.heap
if os.macos:
let contents = try child(bundle_root.value, "Contents")
defer strings.release(contents)
let binaries = try child(contents, "MacOS")
defer strings.release(binaries)
let resources = try child(contents, "Resources")
defer strings.release(resources)
try copy_into(executable.value, binaries, definition.name, 0o755)
if icon_name.length > 0: try copy_into(icon_source.value, resources, icon_name, 0o644)
let plist = try paths.join(contents, "Info.plist")
defer plist.release()
let icon_entry = try strings.format(text[4096..], f" <key>CFBundleIconFile</key>\n <string>{icon_name}</string>\n") if icon_name.length > 0 else ""
try write_text(plist.value, try strings.format(text[..<4096], f"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE plist PUBLIC \"-//Apple//DTD PLIST 1.0//EN\" \"http://www.apple.com/DTDs/PropertyList-1.0.dtd\">\n<plist version=\"1.0\">\n<dict>\n <key>CFBundleName</key>\n <string>{definition.application.name}</string>\n <key>CFBundleDisplayName</key>\n <string>{definition.application.name}</string>\n <key>CFBundleIdentifier</key>\n <string>{definition.application.identifier}</string>\n <key>CFBundleExecutable</key>\n <string>{definition.name}</string>\n <key>CFBundleVersion</key>\n <string>{definition.version}</string>\n <key>CFBundleShortVersionString</key>\n <string>{definition.version}</string>\n <key>CFBundlePackageType</key>\n <string>APPL</string>\n <key>CFBundleInfoDictionaryVersion</key>\n <string>6.0</string>\n{icon_entry} <key>NSHighResolutionCapable</key>\n <true/>\n <key>NSPrincipalClass</key>\n <string>NSApplication</string>\n</dict>\n</plist>\n"))
return
if os.windows:
# the program folder: the executable and its icon, as a Start Menu shortcut expects
try copy_into(executable.value, bundle_root.value, built_name, 0o755)
if icon_name.length > 0: try copy_into(icon_source.value, bundle_root.value, icon_name, 0o644)
return
# Linux AppDir: the program under its own name, so its windows' class and
# /proc/self/exe name it, and AppRun a script that runs it (through the
# symlink ~/.luce/bin keeps too), with a desktop entry and the icon beside.
try copy_into(executable.value, bundle_root.value, definition.name, 0o755)
let staged = try paths.join(bundle_root.value, ".AppRun.new")
defer staged.release()
try write_text(staged.value, try strings.format(text[..<4096], f"#!/bin/sh\nexec \"$(dirname \"$(readlink -f \"$0\")\")/{definition.name}\" \"$@\"\n"))
try copy_into(staged.value, bundle_root.value, "AppRun", 0o755)
try files.remove_file((c.str)staged.value)
if icon_name.length > 0: try copy_into(icon_source.value, bundle_root.value, icon_name, 0o644)
var entry_name: u8[96]
let desktop = try paths.join(bundle_root.value, try strings.format(entry_name, f"{definition.name}.desktop"))
defer desktop.release()
var stem = icon_name
for i in 0..<icon_name.length:
if icon_name.bytes[i] == '.': stem = (str)icon_name.bytes[..<i]
let icon_line = try strings.format(text[4096..], f"Icon={stem}\n") if stem.length > 0 else ""
try write_text(desktop.value, try strings.format(text[..<4096], f"[Desktop Entry]\nType=Application\nName={definition.application.name}\nExec=AppRun\n{icon_line}Terminal=false\nStartupWMClass={definition.name}\nX-Luce-Identifier={definition.application.identifier}\nX-Luce-Version={definition.version}\n"))
# mark: Where applications are installed ======================================================
extern func access(path: c.str, mode: i32) -> i32
func writable(path: str) -> bool!:
let terminated = try strings.copy(path)
defer strings.release(terminated)
return files.exists((c.str)terminated) and access((c.str)terminated, 2) == 0
func environment_or(name: c.str, fallback: str) -> str!:
if let chosen = os.env(name):
if chosen.length > 0: return try strings.copy(chosen)
return try strings.copy(fallback)
## The user's home: HOME, or on Windows USERPROFILE where no HOME is set.
func user_home() -> str!:
if let user = os.env((c.str)"HOME"): return try strings.copy(user)
if os.windows:
if let profile = os.env((c.str)"USERPROFILE"): return try strings.copy(profile)
error(invalid, "HOME is not set; set LUC_HOME")
## Where installed applications live: /Applications on macOS (~/Applications when the
## user may not write there), the XDG data directory on Linux (~/.local/share), and
## %LOCALAPPDATA%\Programs on Windows. LUC_APPLICATIONS overrides it.
pub func shelf() -> str!:
if let chosen = os.env((c.str)"LUC_APPLICATIONS"):
try ensure_directory(chosen)
return try strings.copy(chosen)
let user = try user_home()
defer strings.release(user)
if os.macos:
if try writable("/Applications"): return try strings.copy("/Applications")
return try child(user, "Applications")
if os.windows:
let fallback = try paths.join(user, "AppData/Local")
defer fallback.release()
let data = try environment_or((c.str)"LOCALAPPDATA", fallback.value)
defer strings.release(data)
return try child(data, "Programs")
let dot_local = try child(user, ".local")
defer strings.release(dot_local)
let share = try child(dot_local, "share")
defer strings.release(share)
let data = try environment_or((c.str)"XDG_DATA_HOME", share)
# Returned to the caller, who releases it; only a failure here drops it.
errdefer strings.release(data)
try ensure_directory(data)
return data
## Where the desktop's launcher looks: the shelf itself on macOS, its `applications`
## directory on Linux, the Start Menu's Programs on Windows (LUC_START_MENU overrides).
func launcher() -> str!:
let directory = try shelf()
if os.macos: return directory
defer strings.release(directory)
if os.linux: return try child(directory, "applications")
if let chosen = os.env((c.str)"LUC_START_MENU"):
try ensure_directory(chosen)
return try strings.copy(chosen)
let user = try user_home()
defer strings.release(user)
let roaming = try paths.join(user, "AppData/Roaming")
defer roaming.release()
let data = try environment_or((c.str)"APPDATA", roaming.value)
defer strings.release(data)
return try join(data, "Microsoft/Windows/Start Menu/Programs")
## Append `path` and a newline to a record of what an install created.
func note(record: u8[], used: usize*, path: str) -> !:
if *used + path.length + 1 > record.length: error(invalid, "an install records too many paths")
for byte in path.bytes:
record[*used] = byte
*used += 1
record[*used] = '\n'
*used += 1
## A Windows shortcut through the shell's own COM object, as installers make them.
func shortcut(link: str, target: str, directory: str) -> !:
var script: u8[4096]
let command = try strings.format(script, f"$s = (New-Object -ComObject WScript.Shell).CreateShortcut('{link}'); $s.TargetPath = '{target}'; $s.WorkingDirectory = '{directory}'; $s.Save()")
let text = try strings.copy(command)
defer strings.release(text)
let arguments: c.str[4] = ["-NoProfile", "-NonInteractive", "-Command", (c.str)text]
let ran = try process.run("powershell", arguments)
defer ran.release()
if ran.value.exit_code != 0: error(invalid, "could not create the Start Menu shortcut")
## Install the bundle luc built (`built`) where the system keeps applications and make the
## desktop find it. Returns the executable to link commands to; every path created is
## noted in `record` for uninstall. macOS: Name.app in the shelf, which Launchpad and
## Spotlight index. Linux: the AppDir in luce/apps under the data directory and a desktop
## entry.
## Windows: the program folder under Programs and a Start Menu shortcut.
pub func place(definition: pkg.Definition*, built: str, record: u8[], used: usize*) -> str!:
let directory = try shelf()
defer strings.release(directory)
var budget: usize = 20000
var name: u8[128]
if os.macos:
let target = try paths.join(directory, try strings.format(name, f"{definition.application.name}.app"))
defer target.release()
try refuse_foreign(target.value, definition.application.identifier)
try replace_tree(built, target.value, &budget)
try note(record, used, target.value)
var inner: u8[256]
return try join(target.value, try strings.format(inner, f"Contents/MacOS/{definition.name}"))
if os.linux:
let store = try linux_store()
defer strings.release(store)
let target = try paths.join(store, paths.base(built))
defer target.release()
try replace_tree(built, target.value, &budget)
try note(record, used, target.value)
let entries = try launcher()
defer strings.release(entries)
let entry = try paths.join(entries, try strings.format(name, f"{definition.name}.desktop"))
defer entry.release()
let text = try new u8[5120] --- in memory.heap
defer free(text) in memory.heap
# No Icon= without an icon: a directory there fails desktop-file-validate.
let icon = try strings.format(text[4096..], f"Icon={target.value}/{paths.base(definition.application.icon)}\n") if definition.application.icon.length > 0 else ""
# StartupWMClass matches the window's WM_CLASS (the program's name) to this entry.
try write_text(entry.value, try strings.format(text[..<4096], f"[Desktop Entry]\nType=Application\nName={definition.application.name}\nExec=\"{target.value}/AppRun\"\n{icon}Terminal=false\nStartupWMClass={definition.name}\nX-Luce-Identifier={definition.application.identifier}\nX-Luce-Version={definition.version}\n"))
try note(record, used, entry.value)
return try join(target.value, "AppRun")
let target = try paths.join(directory, definition.application.name)
defer target.release()
try replace_tree(built, target.value, &budget)
try note(record, used, target.value)
var executable_name: u8[128]
let executable = try join(target.value, try strings.format(executable_name, f"{definition.name}.exe"))
errdefer strings.release(executable)
let menu = try launcher()
defer strings.release(menu)
try ensure_directory(menu)
let link = try paths.join(menu, try strings.format(name, f"{definition.application.name}.lnk"))
defer link.release()
try shortcut(link.value, executable, target.value)
try note(record, used, link.value)
return executable
## luc's own directory for Linux AppDirs, inside the data directory, so an application's
## files never share a directory with the data it keeps there itself.
func linux_store() -> str!:
let directory = try shelf()
defer strings.release(directory)
let luce = try child(directory, "luce")
defer strings.release(luce)
return try child(luce, "apps")
## An application of the same name that luc did not install (another identifier) stays.
func refuse_foreign(target: str, identifier: str) -> !:
let plist = try paths.join(target, "Contents/Info.plist")
defer plist.release()
if not files.exists((c.str)plist.value): return
let text = try files.read((c.str)plist.value, limit = 65536)
defer text.release()
var wanted: u8[320]
if not strings.contains((str)text.value, try strings.format(wanted, f"<string>{identifier}</string>")):
error(invalid, "another application of that name is installed there; luc will not replace it")
## Put `source` at `target`, replacing what is there. The old tree is moved aside
## first and removed only once the new one is complete: a running program's files
## cannot be moved on Windows, so an application in use fails here with nothing
## changed, and a failed copy puts the old tree back.
func replace_tree(source: str, target: str, budget: usize*) -> !:
let terminated = try strings.copy(target)
defer strings.release(terminated)
if not files.exists((c.str)terminated):
try copy_tree(source, target, budget)
return
var aside_text: u8[1200]
let aside = try strings.copy(try strings.format(aside_text, f"{target}.previous"))
defer strings.release(aside)
if files.exists((c.str)aside): try files.remove_tree((c.str)aside)
files.rename((c.str)terminated, (c.str)aside, replace = false) catch failure:
error(failure.code, "the installed application is in use; close it and run the command again")
errdefer restore_tree((c.str)terminated, (c.str)aside)
try copy_tree(source, target, budget)
_ = files.remove_tree((c.str)aside) catch: recover ()
func restore_tree(target: c.str, aside: c.str):
_ = files.remove_tree(target) catch: recover ()
_ = files.rename(aside, target, replace = false) catch: recover ()
## Remove something place() created. Only an entry directly inside the shelf or the
## launcher directory is touched, whatever the record says.
pub func unplace(path: str) -> !:
let directory = try linux_store() if os.linux else try shelf()
defer strings.release(directory)
let entries = try launcher()
defer strings.release(entries)
if not directly_inside(path, directory) and not directly_inside(path, entries): return
let terminated = try strings.copy(path)
defer strings.release(terminated)
if not files.exists((c.str)terminated): return
let info = try files.metadata((c.str)terminated, follow_symlinks = false)
if info.kind == files.FileKind.directory: try files.remove_tree((c.str)terminated)
else: try files.remove_file((c.str)terminated)
func directly_inside(path: str, directory: str) -> bool:
if directory.length == 0 or path.length <= directory.length + 1 or not strings.starts_with(path, directory): return false
let separator = path.bytes[directory.length]
if separator != '/' and separator != '\\': return false
for byte in path.bytes[directory.length + 1..]:
if byte == '/' or byte == '\\': return false
return true