Hall - A project manager for the Guile programming language

Hall – A project manager for the Guile programming language

11 juin 2020

I'm going to introduce you to Hall, a tool to assist you in the development and distribution of Guile programs. I won't cover all of Hall's features. Just something to give you a try ;–)

You'll see how to create a Guile project from scratch using Hall sugar, how to build it, how to test it, and how to distribute it !

Modern programming languages often come with their own package manager to facilitate code sharing between developers.

Sometimes, these tools are not limited to pure and simple package management and include tools for building executables, running test suites, deploying the software, and more if affinity :

Ruby has RubyGems.
Python has Pip.
Javascript has Node.
Kotlin has Gradle.
Go has Go.
Rust has Cargo.

In version 2, Guile had GuildHall, led by Ian Price. A tool able to install, update and uninstall softwares coded in Guile. The project already had a good package base.

But it's a thing of the past. Now there is Hall, a project led by Alex Sassmannshausen since 2018 that supports version 3 of the language and takes advantage of the features of Guix (and that's cool)!

According to the README of the Hall repository, here is what it is capable of:

Manage a Guile project hierarchy from one project spec file.

Transparently support the GNU build system for maximum portability.

Leverage tight coupling to Guix for reliability & confidence.

Profit.

Not knowing how to use the GNU Building System, Hall helps me out of a jam. It clearly leverage autotools features in a handy manner.

With Hall, everything revolves around the hall.scm file that is used to specify a project. With this specification in place, Hall will be able to generate the infrastructure to build, test and distribute the project properly.

At the moment, Hall is in version 0.3.1. To install it, I use Guix (as for everything related to Guile).

$ guix install guile-hall

It works for GNU/Linux users. What about others ? Well, for MacOS folks, Aleix Conchillo Flaqué is hacking Guile Homebrew Tap to bring Guile universe to the Apple one. For MS Windows, I have nothing to serve you right now, but I hope I will.

Now, let's get on with the demonstration.

Initialize a new Guile project with Hall:

$ hall init dummy --author="Red Nose Hacker" --license="gpl3+" --prefix="guile" --execute

Voila, a new project called dummy has been initialized! Hall created a guile-dummy directory (because I asked for it to be prefixed) and built a pro tree in it! A lot of things were done automatically (even the doc is prepared), I'll let you explore by yourself.

$ cd guile-dummy
$ tree -a
.
├── COPYING
├── doc
│ └─ dummy.texi
├── dummy
├─ dummy.scm
├─ .gitignore
├─ guix.scm
├── HACKING
├── hall.scm
├── README -> README.org
├── README.org
├── scripts
└── tests

As I said earlier, the hall.scm file is central. This is the project specification file. Hall generated this tree with the following specification:

$ cat hall.scm 
(hall-description
  (name "dummy")
  (prefix "guile")
  (version "0.1")
  (author "Red Nose Hacker")
  (copyright (2020))
  (synopsis "")
  (description "")
  (home-page "")
  (license gpl3+)
  (dependencies `())
  (files (libraries
           ((scheme-file "dummy") (directory "dummy" ())))
         (tests ((directory "tests" ())))
         (programs ((directory "scripts" ())))
         (documentation
           ((org-file "README")
            (symlink "README" "README.org")
            (text-file "HACKING")
            (text-file "COPYING")
            (directory "doc" ((texi-file "dummy")))))
         (infrastructure
           ((scheme-file "guix")
            (text-file ".gitignore")
            (scheme-file "hall")))))

Scan the project after the first modifications

Let's add some code to this project, for example a function with a test.

In the dummy.scm file copy/paste the following code:

(define-module (dummy))

(define-public (say-hi)
  "Hi hackers !")

Then, create a tests/harness.scm file and copy/paste the following code :

(define-module (tests-harness)
  #:use-module (srfi srfi-64)
  #:use-module (dummy))

(module-define! (resolve-module '(srfi srfi-64))
		'test-log-to-file #f)

(test-begin "test-suite")

(test-equal "Greetings"
  "Hi hackers !"
  (say-hi))

(test-end "test-suite")

That's it, now Hall needs to be informed that the test file has been added.

$ hall scan --execute

With the scan, Hall detected the test file and added it to the specification.

((hall-description
  (name "dummy")
  (prefix "guile")
  (version "0.1")
  (author "Red Nose Hacker")
  (copyright (2020))
  (synopsis "")
  (description "")
  (home-page "")
  (license gpl3+)
  (dependencies `())
  (files (libraries
           ((scheme-file "dummy") (directory "dummy" ())))
         (tests ((directory "tests" ((scheme-file "harness")))))
         (programs ((directory "scripts" ())))
         (documentation
           ((org-file "README")
            (symlink "README" "README.org")
            (text-file "HACKING")
            (text-file "COPYING")
            (directory "doc" ((texi-file "dummy")))))
         (infrastructure
           ((scheme-file "guix") (scheme-file "hall")))))

(Well we can also see that the .gitignore file disappears from the spec' i don't know why but... it's not the subject haha).

Generate the Build Infrastructure

With the updated project specification, we can now generate what is needed to build our software.

$ hall dist --execute

It's as simple as that, and yet the elements necessary for autotools to build the project have been created.

$ tree -a
.
├── AUTHORS
├── build-aux
│   └── test-driver.scm
├── ChangeLog
├── configure.ac
├── COPYING
├── doc
│   └── dummy.texi
├── dummy
├── dummy.scm
├── .gitignore
├── guix.scm
├── HACKING
├── hall.scm
├── Makefile.am
├── NEWS
├── pre-inst-env.in
├── README -> README.org
├── README.org
├── scripts
└── tests
    └── harness.scm

Automation is beautiful... As I said, I have not any relevant knowledge about autotools so move on.

Build the project

It's time for me to show you why I think it's cool that Hall is taking advantage of Guix's features. Well OK, it's well explained in the HACKING file but it's my pleasure.

To build the project, you'll need some libraries, the famous dependencies. For projects managed with Hall (v0.3.1), you need at least :

autoconf
automake
pkg-config
texinfo
and guile-hall (but we'll say you already have it)

If they're already installed on your system, cool. If not, you have to install them by hand, not cool. But if you have Guix, you can take advantage of the package recipe Hall made for you in the guix.scm file! Indeed, you will be able to create a virtual environment, which will have the necessary dependencies, to build the project. Watch out for the eyes:

$ guix environment --load=guix.scm

Bim, when it's over, you find yourself in your environment dedicated to the development of the dummy project.

You can now build and test the project:

[dev] $ autoreconf -vfi && ./configure && make check && exit

I'll get you the excerpt from the test report. I love tests:

PASS: tests/harness.scm
============================================================================
Testsuite summary for guile-dummy 0.1
============================================================================
# TOTAL: 1
# PASS: 1
# SKIP: 0
# XFAIL: 0
# FAIL: 0
# XPASS: 0
# ERROR: 0
============================================================================

Our only test was well executed and passed! So our project can now be distributed serenely.

Distribute the project

Edit: from the Guile/Guix Mailing-List, divoplade suggests :

you may also want to consider adding a quick line for “make distcheck”, which makes sure that the distribution can be built from source (detect missing files, out-of-tree build errors, and a few other goodies)

To distribute/share the code, a fairly common practice is to make an archive of it. But what to put in the archive so that our peers can reuse it without any problem? Hall knows, and he's doing it for you!

$ guix environment -l guix.scm
[dev] $ make dist && exit

Let's send the guile-dummy-0.1.tar.gz tarball to the world !

Cleaning the project

For the maniacs:

$ make clean && hall clean --execute

Going further

I didn't mention the documentation, which is also managed by Hall and ready to use!

$ ./pre-inst-env info doc/dummy.texi

I probably don't have enough detail on the use of the hall command. That's why I strongly encourage you to consult Hall's manual:

$ info guile-hall

Thank you so much for reading this article !

Don't hesitate to give me your opinion, leave a comment, or ask a question via : – E-mail: jeremy AT korwin-zmijowski DOT fr – Mastodon: @jeko@framapiaf.org – Peertube: @jeko@video.tedomum.net – Twitter: @JeremyKorwin

Also, please subscribe so you don't miss the next ones : – blog via Mastodon @jeko@write.as et RSS – screencast via Peertube @jeko@video.tedomum.net et RSS

And most importantly, share the blog and tell your friends it's the best blog in the history of Free Software! No shit!

#english #guile #tool #hall #guix