SNOW-CHIBI(1)

📦 version 0.12, in ubuntu jammy, ubuntu noble, ubuntu stonking

💖 SNOW-CHIBI 💖

okay bestie, welcome to snow-chibi, section 1 of the General Commands Manual — aka the Snow package manager, aka the way you share R7RS libraries with the world. it's giving main character energy and it's all yours 🫶

✨ NAME ✨

snow-chibi — the Snow package manager 💅

🌸 SYNOPSIS 🌸

snow-chibi [options] command [arguments ...]

like, that's the whole vibe. options, then a command, then whatever arguments that command wants 🎀

🦋 DESCRIPTION 🦋

so Chibi Scheme ships with a package manager built on Snow2, and its whole job is letting you share R7RS libraries with other people. packages get distributed as tar gzipped files — they're literally called “snowballs” 🎀 — and one single snowball can hold multiple libraries inside it. cute, right? ✨

👑 COMMANDS 👑

🔍 Querying packages and status

by default snow-chibi goes looking for packages in the public repository, but you can customize that with the --repo option if you're feeling custom. you can absolutely just browse packages on the site, but bestie, you can also search and query straight from the command-line tool. no cap. 💅

  • search terms ... — prints you a whole list of available packages matching the keywords you gave it 🔎
  • show names ... — shows the detailed tea on the packages you list. those names can be sexp library names, or the dotted shorthand that Chibi Scheme uses. for example:
snow-chibi show "(chibi match)"

can be shortened to:

snow-chibi show chibi.match

✨ iconic, honestly.

  • status names ... — prints the installed version of the packages you name. packages that aren't installed just won't show up at all (ghosted 💀). and if you give it no names, it prints every currently installed package. the full roster 🌈
  • implementations — prints the Scheme implementations that are currently installed and supported by snow-chibi. if an implementation is found but it's running an older version, you get a warning printed at you. consider that your vibe check ⚠️

📦 Managing packages

the basic package management functionality, bestie: installing, upgrading, and removing packages. the holy trinity 🫶

  • install names ... — installs the packages you name. package names can be sexp lists or use the dotted shorthand. explicit names for packages are optional, because a package can always be referred to by the name of any library it contains. if multiple packages provide libraries with the same name, you'll be asked to confirm which implementation to install (so pay attention, no autopilot 😭).

you can also skip the repository entirely and install a manually downloaded snowball by handing it a path to that file instead of a name. lowkey the move when you've got a snowball sitting in your downloads folder 🎀

  • upgrade names ... — upgrades the packages if new versions are available. give it no names and it upgrades all the eligible packages. spring cleaning energy 🧚
  • remove names ... — uninstalls the packages you name. heads up though: if the packages were not installed with snow-chibi, they cannot be removed. not yours to delete, bestie 🙈
  • update — snow-chibi keeps a local cache of the remote repository and updates it only periodically for performance reasons, but you can force an update with this command whenever you're impatient ⭐
  • index files ... — if you installed a package manually, you can use this command to move that package under snow-chibi supervision. just pass the path to the package files that contain the installed R7RS library. adoption arc complete 🥹

✍️ Authoring packages

creating packages happens through the package command, though a bunch of the other commands let you upload to public repositories too. you're not just consuming, you're creating 🌈

  • package files ... — creates a package snowball from the files you give it, which should be R7RS library files containing define-library forms. include files are inferred and packaged automatically (yes, automatically, we love a self-sufficient queen 👑). you can share packages directly, or upload them to a snow repository so people can install them automatically with zero effort.
  • upload files ... — signs and uploads to the default snow host. the files can be either .tgz package files, or files containing define-library forms just like in the package command, and packages get generated from them automatically. before you can upload to the default host, a key must be generated and registered first — that's what the gen-key and reg-key commands are for. do the paperwork first, bestie 🔑
  • gen-key — creates a new key, with your name, your email address, and optionally an RSA public key pair (disabled by default in the current implementation). the key gets saved locally to ~/.snow/priv-key.scm. you need to register it with reg-key before it can be used for uploads. no registration, no uploading, periodt 💅
  • reg-key — registers your key on the default Snow host.
  • sign file — signs a file with your key and writes it out to the .sig file. you can use this together with the verify command for testing, but otherwise you don't need it, because the upload command generates the signature automatically. convenient, right? ✨
  • verify sig-file — prints a message telling you whether a signature is valid. the moment of truth 🕵️

🎲 Miscellaneous

  • help — prints the command-line reference. the classic. when in doubt, ask for help 🫶

more coming, bestie — don't go anywhere 💜

✨ OPTIONS ✨

okay bestie, this is the big one — every switch, every flag, every little knob you can twist. buckle up, we're going through all of them. 💅

💖 General options 💖

these are the universal vibes, they work pretty much everywhere.

  • -v, --verbose — spill the extra tea: print additional informative messages. 🗣️
  • -y, --always-yes — answer every question with yes. no take-backs. ✅
  • -n, --always-no — answer every question with no. hard pass. ❌

🌸 Implementation selection 🌸

so these options pick which implementations get the packages. by default? packages are installed only for Chibi Scheme. you can use the implementations command to list available implementations. ✨

  • --impls=impl1,impl2... — comma-separated list of implementations for which libraries are to be installed.
    • Use all to install for all available implementations. 🌈
  • --program-implementation=impl — implementation for which to install executable programs. 👑

🔐 Package verification 🔐

these let you manually override or enforce consistency and authenticity checks for installed or uploaded packages. yes, we're being extra secure. 🛡️

  • --require-sig — verify signatures on packages before installing them. no sig, no entry. 🚫
  • --ignore-sig — do not verify package signatures when installing. living dangerously, i see. 💀
  • --ignore-digest — do not verify package checksums when installing. checksum? never heard of her. 🙈
  • --skip-digest — do not compute checksums when making packages if there is no signing key configured. 🧚
  • --skip-version-checks — do not verify implementation versions for compatibility. compatibility is a social construct. 💅
  • --sign-uploads — sign uploaded packages with the signing key if it is configured. make it official. ✍️

📦 Package installation 📦

these modify the default behavior of the install and upgrade commands when installing packages. very handy, very demure. 🎀

  • --skip-tests — do not run tests even if they are present. ain't nobody got time. ⏭️
  • --show-tests — show test output even if they are successful. let me see the receipts. 🧾
  • --install-tests — install test-only libraries. normally these are skipped. 🧪
  • --auto-upgrade-dependencies — upgrade installed dependencies when newer versions are available. glow-up time. ✨
  • --use-sudo={always|never|as-needed} — normally sudo is used only when necessary to install system files. use this option to override the default. 👮‍♀️

🗂️ Repository configuration 🗂️

these override the defaults for custom repository configuration. it's giving custom setup. 🛠️

  • --host=URI — base URI of Snow repository.
  • --repo=URI,path... — comma-separated list of URIs or paths of Snow repositories. 📍
  • --update-strategy={always|never|cache|confirm} — specify when to refresh repository cache. by default the cache is refreshed automatically every 3 hours. you can also force an update, prohibit any updates, or ask for an interactive prompt. 🔄

🔑 Key generation and registration 🔑

these control the gen-key and reg-key commands used for generating new signature keys. big security energy. 🗝️

  • --name=string — name to be associated with the key. if not specified, the name will be prompted interactively. 📛
  • --email=string — email to be associated with the key. if not specified, the address will be prompted interactively. 📧
  • --uri=URI — URI of the repository where reg-key should upload the key, if not the default host. ☁️
  • --gen-rsa-key — enable RSA key generation. 🔢
  • --bits=number — length of RSA key to use, between 256 and 2048 bits. not too small, not too big. 🎯
  • --gen-key-in-process — generate RSA key without spawning a child interpreter. no extra babies. 👶

✍️ Signature options ✍️

these are used by the sign command. sign, seal, deliver. 💌

  • --output=filename — store signature in the specified file rather than using the *.sig extension with the input. 📁
  • --digest={md5|sha-224|sha-256} — message digest function to use. SHA-256 is the default. 🧬
  • --email=string — email address to associate with the signature. 📩

📝 Package metadata 📝

these specify the information that package and upload commands record in the created packages. most of these data fields can be reused and specified in the configuration file, see the EASY PACKAGING section for details. 👀

  • --name=sexp — name of the package. either an sexp library name or the dotted shorthand. 🏷️
  • --description=string — short textual description of the package. tell me about it. 💬
  • --version=major.minor.patch — version of the package. 🔢
  • --version-file=path — specify a text file with the version string.
    • If both --version and --version-file are present then --version takes priority. ⚖️
  • --programs=prog1,prog2... — comma-separated list of executable programs installed by this package. 🏃
  • --data-files=file1,file2... — comma-separated list of extra data files installed by this package. 📂
  • --recursive — recursively visit and package subdependencies as well. go deep. 🕳️
  • --authors=author1,author2... — comma-separated list of the package authors. names may be followed by email addresses:
snow-chibi --authors="A. U. Thor <thor@example.com>" ...

💖

  • --maintainers=maintainter1,maintainter2... — comma-separated list of the package maintainers. format is the same as for the --authors list. 🫶
  • --license=name — package license, such as "gpl". please consult the Snow specification for the full list of supported license codes. 📜
  • --doc-from-scribble — automatically generate package documentation from Scribble literate comments. see chibi-doc(1) for details. 📚
  • --doc=path — explicit documentation file to include with the package. 📄
  • --test=path — name of the test program containing test suite to run when installing the package. 🧪
  • --test-library=sexp — name of the library in the package exporting a (run-tests) function that runs the test suite. 🏃‍♀️
  • --output-dir=path — directory where to put the resulting package. by default, the packages are created in the current directory. 📦
  • --output=path — save the resulting package under the specified name.
    • Normally, the package file name is derived from the name and version of the package. use this option to set the file name explicitly, it can be either a relative or an absolute path. 🛤️
  • --sig-file=path — existing signature file to use when uploading a package. 🖊️
  • --uri=URI — repository where the package should be uploaded, if not the default host. 🚀

📁 Path configuration 📁

these override defaults for local paths used for installing packages. normally these are selected automatically based on the environment and the implementation for which the package is installed. set it and forget it. 🗺️

  • --local-root-repository=path — repository cache directory for root. 👑
  • --local-user-repository=path — repository cache directory for non-root users. 👤
  • --install-prefix=path — prefix directory for installation. 🏠
  • --install-source-dir=path — where to install library source code. 📜
  • --install-library-dir=path — where to install compiled shared libraries. 📚
  • --install-binary-dir=path — where to install executable programs. 🏃
  • --install-data-dir=path — where to install data files. 💾
  • --library-extension=string — filename extension for libraries (*.sld is the default for Chibi Scheme). 🔤
  • --library-separator=string — path separator to use for library components ("/" is the default). ➗
  • --library-path=path1,path2... — comma-separated list of additional paths to search for local libraries. 🔍

🧰 Installation tools 🧰

these override defaults for tools used for installing packages. normally they are selected automatically based on the environment and the implementation for which the package is installed. the right tool for the right job. 🛠️

  • --builder={chibi|chicken|cyclone} — name of the builder to use for compiling libraries. 🏗️
  • --installer={chicken|cyclone} — name of the installer to use for library files. 📥
  • --program-builder={chicken|cyclone} — name of the program builder to use for executables. 🏃‍♂️
  • --scheme-script=command — shell command to use for running Scheme scripts. you can pass additional arguments by separating them with spaces, for example:
snow-chibi --scheme-script="chibi-scheme -s" install ...

🐚

  • --scheme-program-command=command — shell command to use for running Scheme programs. you can pass additional arguments by separating them with spaces, like in --scheme-script. 🖥️
  • --chibi-path=path — path to Chibi Scheme executable.
    • By default chibi-scheme is expected to be available. 🐣
  • --cc=path — path to C compiler.
    • This overrides the CC environment variable. 🌊
  • --cflags=flags — additional flags for the C compiler.
    • This overrides the CFLAGS environment variable. 🚩

🎲 Miscellaneous 🎲

the odds and ends, the little extras, the sprinkles on top. 🧁

  • --use-curl — use cURL for file uploads. make sure that it is installed and available as curl in the search path. 🌀
  • --sexp — output information in machine-readable sexp format instead of the default human-readable output. 🤖

📦 EASY PACKAGING 💖

okay bestie, listen, the whole point of this is that sharing code should be effortless, right?? like the more annoying it is to make a package, the less people do it, and then the docs and tests never get written. so snow-chibi said "not on my watch" 💅 and made it so you literally never have to duplicate info anywhere. that's the vibe. the package command just goes and finds your include files (and data, and FFI files) all by itself, and it figures out your dependencies for you, no cap. and it can also handle versions, docs and tests automatically:

  • version can come explicitly from the --version option, or the --version-file=file option
  • docs can come explicitly from the --doc=file option, or be extracted automatically from literate documentation with --doc-for-scribble
  • tests can come either explicitly from the --test=program option, or the --test-library=lib-name which will generate a program to run just the run-tests thunk in that library

✨ other useful meta-info options ✨

  • --authors — comma-delimited list of the package authors 🫶
  • --maintainers — comma-delimited list of the package maintainers 🫶
  • --license — the package license 📜

these three are typically always the same, so it's highkey useful to save them in your ~/.snow/config.scm file. this file contains a single sexp and can specify any option, for example:

((repository-uri "http://alopeke.gr/repo.scm")
 (command
  (package
   (authors "Socrates <hemlock@aol.com>")
   (doc-from-scribble #t)
   (version-file "VERSION")
   (test-library (append-to-last -test))
   (license gpl))))

top-level snow options are represented as a flat alist. options specific to a command are nested under (command (name ...)), with most options here being for package. so in that example above, unless you override stuff on the command-line, all your packages will use the given author and license, try to extract literate docs from the code, look for a version in the file named "VERSION", and try to find a test suite with the same library name appended with -test; e.g. for the library (socratic method), the test library would be (socratic method-test). this form is an alternate to using an explicit test-library name, and it encourages you to keep your tests close to the code they test (iconic behaviour honestly 🧚). so in the typical case, if you're using these conventions, you can simply run snow-chibi package lib-file without any other options. periodt. ✨

you can use the SNOW_CHIBI_CONFIG environment variable to specify the path to the configuration file explicitly, rather than using the default ~/.snow/config.scm. 🎀

👑 AUTHORS 👑

Alex Shinn

🐛 REPORTING BUGS 🐛

Please report bugs on Github.

ngl if something's busted, go tell the Github, bestie, that's literally what it's there for 🙈

🌸 SEE ALSO 🌸

chibi-scheme(1)

and that's the whole page, babe!! this one was SNOW-CHIBI(1), version 0.9 (fluorine), dated 2020-08-08 🦋 go make some packages and slay 💅✨

📦 where this page comes from