From 6fde1310b2bf660de0cbe67948a175da9ea82c27 Mon Sep 17 00:00:00 2001 From: Sirisak Lueangsaksri <1087399+spywhere@users.noreply.github.com> Date: Sun, 14 Apr 2024 00:43:39 +0700 Subject: [PATCH] docs(systems): add system APIs docs --- docs/package.md | 5 ++- systems/README.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 108 insertions(+), 1 deletion(-) create mode 100644 systems/README.md diff --git a/docs/package.md b/docs/package.md index a80b365..3d98a2e 100644 --- a/docs/package.md +++ b/docs/package.md @@ -106,7 +106,7 @@ the mentioned package. ## Supported Package Managers -Check out [systems API](/systems) for all available command on each supported +Check out [system APIs](/systems) for all available command on each supported systems. ## Conditions @@ -127,6 +127,9 @@ if various kind of software is exists or not. To name a few, you could use Check out [built-in API references](/lib) for a function prefixed with `has_`. +As certain systems might also implemented a similar function, be sure to check +out [system APIs](/systems) as well. + ### Skip installation for a specific system To not install a package on any particular system, simply NOT call a function diff --git a/systems/README.md b/systems/README.md new file mode 100644 index 0000000..41ceb58 --- /dev/null +++ b/systems/README.md @@ -0,0 +1,104 @@ +# System APIs + +System APIs are functions that only available on a certain system. + +System APIs will automatically get loaded based on the system running the +installer. A base system will always get loaded, then a specific system. + +An installer will try to determine the system name primarily by running +`uname -s`. For Linux-based, the field `ID_LIKE` in `/etc/os-release` will be +used instead before fallback to `ID`. If `/etc/os-release` is not found, then +it will detect the system as followed. + +- If `/etc/debian_version` is found, a system will considered `debian` +- If `/etc/alpine-release` is found, a system will considered `alpine` +- Otherwise, considered as `linux` system + +During the initial self-check, if a system file for a given system is not +found, then the installer will simply bail out with a message on unsupported +system. + +## Supported Systems + +Currently, the installer support the following systems + +- macOS +- Linux + - Debian + - Raspberry Pi OS + - Ubuntu + +A new system can be easily added, check out on how to add a +[support for a new system](#Support-a-new-system) below. + +## Debian Interface + +- `use_apt_repo `: Add a package repository to source list + - `repo`: Repository URL to be added +- `use_apt `: Install a given package using APT + - `package`: Package name +- `use_dpkg `: Install a .dpkg package from the given URL + - `name`: Display name + - `url`: URL to .dpkg file +- `use_dpkg `: Install a .dpkg +package from the given format URL, and fetch the latest version using Git tag +from the given URL, otherwise fallback to install a fallback version + - `name`: Display name + - `url`: URL to a Git repository to be put into a format URL as well as for +fetching latest version + - `format url`: URL to .dpkg file + - `fallback version`: Fallback version to be put into a format URL + +## macOS Interface + +- `has_app `: Check if an app is installed + - `name`: Application name (name of directory ends with `.app`) +- `has_screensaver `: Check if a screensaver is installed + - `name`: Screensaver name +- `use_brow `: Install a package using Homebrew (Intel version) + - `name`: Package name + - `kind`: Either `formula` or `cask` +- `use_brew `: Install a package using Homebrew (Native version) + - `name`: Package name + - `kind`: Either `formula` or `cask` +- `use_brew_tap `: Add Homebrew tap + - `name`: Tap name +- `use_mas `: Install an app from Mac AppStore using MAS + - `package`: Package name + - `appid`: MAS Application ID +- (Deprecated) `use_nativefier ...`: Create an app for +the given URL + - `package`: Package name + - `url`: URL to turned into an app + - `flags`: Flags to passed to nativefier + +## Support a new System + +A system is simply an implementation of the abstract +[base system](/systems/base.sh). + +The following functions can be implement on the system and will override the +base system implementation. + +### Base Interface + +- (Optional) `system_usage`: Print a custom help message for this system +- (Optional) `setup`: A function that get run before gathering packages and setups +- `install_git`: A function that will install Git for this system + +### Common Interface + +- `update `: A function that will perform a system-wide update or upgrade + - `mode`: Either `update` or `upgrade` will be passed +- `install_packages ...`: A function that will perform a package +installation + - `packages`: A list of packages to be installed +- (Optional) `install_bins ...`: A function that will perform a +direct binary installation + +### Introduce a New Interface + +To introduce a new system API (such as to support a different package manager), +simply add a stub implementation (implementation that does nothing) to the base +system and implement such interface in the new system. This would make a newly +introduced API only available in this new system.