Introduction to Blocks

For several years I've been working on WIRL, a Delphi library for building REST servers, and more recently on MCPConnect, another Open Source library for building MCP servers. Both projects rely on several other Delphi libraries for various tasks (JSON serialization, JWT support, OpenAPI, logging, etc.), and this makes installing the two products fairly complex.

We looked for several ways to simplify the installation process for these two libraries, and also evaluated various Package Managers, including obviously GetIt and other Open Source options, but none of them gave us the immediacy and simplicity we were looking for. In the end, we decided to try building one ourselves. I'm not claiming that what we built is necessarily the best, but it offers a combination of features that's hard to find together in a single product.

The tool we built is called Blocks, an Open Source command-line tool written in Delphi.

Main features

• Installation via WinGet: one of our top priorities was making the installation of Blocks itself as simple as possible. We therefore decided to use WinGet to distribute Blocks. Additionally, Blocks will let you know when an update is available, and you can update it automatically with Blocks upgrade.
• Workspace: perhaps the most important concept in Blocks is the Workspace. Right after installing it, the first thing to do is create a directory to use for installing the libraries you're interested in. This directory will be tied to a specific Delphi version and (if it exists) to a specific registry key (see the -r option in IDE Command Line Switches). This way you can install different versions of the same library on different Delphi versions, but also multiple copies on the same version.
• Open library repository: supported libraries must be registered in a GitHub repository, and they don't need to have any particular characteristics. You just need to add the manifest (one per version) to the Blocks repository via a pull request. There are already 14 libraries available at the moment.
• Dependency management: every supported library must have a version number specified in its manifest, following the SemVer model. The manifest can also specify one or more dependencies. Each dependency can also indicate a version number (e.g. 1.2.3 - a specific version, or ^1.2.3 - any 1.*.* version greater than or equal to 1.2.3).
• Full library management: Blocks offers many ways to manage libraries. The main functions are: installation and uninstallation, rebuilding a library, searching available libraries, listing installed libraries, viewing libraries and their dependencies, and more.

Tutorial

In this introduction I want to walk through a short guide. First of all, I recommend opening a recent version of Delphi with the -r option, so you can experiment on a separate registry key without affecting the Delphi version you use for development.

"C:\Program Files (x86)\Embarcadero\Studio\37.0\bin\bds.exe" -r Blocks

Now you can install Blocks: open a terminal and type:

> winget install DelphiBlocks.Blocks

Then check that it works:

> blocks 

You should see the logo along with the version number. Blocks will also tell you that the current directory is not a Workspace. So let's create a Workspace to work in:

> mkdir c:\dev\WorkspaceD13
> cd c:\dev\WorkspaceD13
> blocks init

Blocks will show you all the installed Delphi versions, specifying the registry key where applicable. Choose the one you created earlier and proceed. At the end of this operation, Blocks will create a .blocks directory containing information about the Workspace, the installed libraries, a copy of the repository, and the binaries generated by compilation (dcu, bpl, dcp, etc.).

To see which libraries are currently available for installation, you can use the command:

> blocks search

You can also pass it a search string. At this point we can install a library by specifying its id (in the form vendor.name) or its short name. For example:

> blocks install taurustls

WARNING: if you have the Delphi version tied to the Workspace open, you should close it before installing or uninstalling. This is because Blocks will modify some entries in the Windows registry (Search Path, DCU Path, Browsing Path, etc.)

At this point I think you've got the idea. You can also try installing more complex packages such as WiRL or MCPConnect, which will automatically download their dependencies as well. If you try to uninstall them, however, only the main library will be removed.

I recommend trying blocks help and blocks help [command_name] to explore all the available features:

> blocks help

Delphi package manager: download, compile and register packages from a
GitHub-hosted repository into your Delphi/RAD Studio installation.

Usage: Blocks <command> [options]

Commands:
  install <package>      Install a package by id (vendor.name) or name.
  build <package>        Recompile an already-installed package without downloading it.
  uninstall <package>    Remove a package from the workspace and database.
  init                   Initialise the workspace and download the package repository.
  list                   List packages installed in the current workspace.
  product [name...]      Show Delphi installations. Pass names to filter and get details.
  search [pattern]       Search the repository index by id, name, description or keywords.
  config                 Read or write workspace or system configuration values.
  view <id[@version]>    Show details of a package from the repository.
  version                Print the version of the blocks executable.
  upgrade                Check for a newer release and download the setup if available.
  help [command]         Show this message, or detailed help for a specific command.

Examples:
  Blocks init /product delphi13
  Blocks install owner.package
  Blocks install package /silent
  Blocks uninstall owner.package
  Blocks search json
  Blocks list
  Blocks help install

Conclusions

Blocks is currently at version 0.6.2. There's definitely still work to do, but it's already usable for many real-world scenarios. In the official repository there's also a docs directory, where you can find the official documentation, including the TODO list, the manifest structure, and the Blocks command-line guide.