Xiden Guide
1 Introduction
2 Setup
3 Package Definitions
4 Launchers
5 Practice
8.2

Xiden Guide

Sage L. Gerard <sage at sagegerard dot com>

Here you learn what Xiden is, what it can do for you, and how to practice using it.

For all documentation, see Xiden Documentation.

1 Introduction

Xiden White Paper covers the thinking behind Xiden.

You can think of Xiden as a zero-trust, Guix-like package manager. But in truth, Xiden is a programming model for software distribution. Package management, CI/CD, and content management are possible use cases. You provide configuration and code to shape Xiden to your particular project, which does not have to be implemented in Racket.

Use Xiden if you are a developer who wants to control how software arrives on a system, quickly. End-users benefit from at least knowing about Xiden because they can have their own say over how Xiden-powered projects operate on their system. In that sense, Xiden as a model gives developers and users more options to freely associate and share work.

These benefits of using Xiden affect developers and end-users. Developers would realize the benefits first, but they are equipped to pass them along to their users.

2 Setup

After installing Xiden, you will have a xiden command available for your system.

First, make sure the following programs are available in your PATH.

To build from source, clone or download Xiden from GitHub and run make in the source directory.

Next, run raco pkg install xiden. If this fails, then make sure you do not have a conflicting version installed.

The xiden command should now be available.

3 Package Definitions

A package definition is a program, and this one creates a familiar greeting in a text file.

"definition.rkt"

#lang xiden
 
(input "hello.txt"
  (artifact (text-source "Hello, world!") #f #f))
 
(output "default"
  (keep-input "hello.txt"))

We define an input as a named source of data. You’ll later learn what the other terms mean, and how they can be adjusted to use the network, verify downloads, and even use your own notation for external resources.

We define an output as a named subprogram that turns inputs into files. We’ll install that output in the next section.

4 Launchers

This launcher program starts and controls Xiden.

"my-xiden.rkt"

#lang xiden/launcher
(module+ main (launch-xiden!))

Xiden built-in launcher is called xiden, and it actually has the same implementation! The difference is that we control our launchers. Save the above code into my-xiden.rkt and give it the definition from the previous section.

  $ racket my-xiden.rkt do ++install-abbreviated definition.rkt

This command will give you first of many reasons for why it won’t work, because all launchers start with zero-trust. You must explicitly allow all relevant details for security. We won’t neglect security, but we’ll use this production-unsafe launcher until you can work with zero-trust.

"my-xiden.rkt"

#lang xiden/launcher
 
(current-chfs (list snake-oil-chf))
(XIDEN_TRUST_BAD_DIGEST #t)
(module+ main (launch-xiden!))

This launcher has a low bar, so run the same do command. A symbolic link will appear. Compare the definition to output to start connecting some dots. To uninstall the output, delete the link and run the garbage collection command.

  $ rm my-first-package && racket my-xiden.rkt gc

  Recovered 13 bytes

To recap, launchers build software from package definitions and issue links to their outputs. You’re now equipped to learn more by example.

5 Practice

You installed Xiden, wrote a package definition, wrote a launcher, then used the launcher to (un)install something.

This guide left a lot out to make one point: everything in Xiden boils down to launchers and package definitions. Now that you know what both are, you can understand examples in context. Run this command to print where Xiden’s examples are on your disk. Go to that directory and look for a README. From there, practice.

  racket -e '(~a (collection-file-path "examples" "xiden"))'

At the end you’ll be comfortable reading Xiden Reference and can organize your own software distribution setup. Once you distribute your custom launcher using xiden, things really start to open up.

Thank you for trying Xiden, and I hope it brings you good fortune. My name is Sage, and you can reach me through my website.