DEV Community

Cover image for Introduction to Blocks
Luca Minuti
Luca Minuti

Posted on

Introduction to Blocks

#delphi #tooling

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
Enter fullscreen mode Exit fullscreen mode

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

> winget install DelphiBlocks.Blocks
Enter fullscreen mode Exit fullscreen mode

Then check that it works:

> blocks
Enter fullscreen mode Exit fullscreen mode

Blocks home

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.)

You can also install a specific version of a library. To see which versions are available, use the view command with the /versions option:

blocks view paolo-rossi.delphi-neon /versions
Enter fullscreen mode Exit fullscreen mode

Once you've found the version you're interested in, you can install it by appending @ followed by the version number to the package id:

> blocks install paolo-rossi.delphi-neon@2.1.0
Enter fullscreen mode Exit fullscreen mode

This dependency mechanism also comes into play when installing more complex libraries. Let's try installing WiRL:

> blocks install wirl
Enter fullscreen mode Exit fullscreen mode

In this case we get an error: WiRL requires delphi-neon ^3.1.0, but we've installed version 2.1.0. We can fix the problem by updating Neon. Notice that we don't specify a precise version, but rather the one indicated by the dependency: this way Blocks will install the latest available 3.x.x version:

> blocks update delphi-neon@^3.1.0
Enter fullscreen mode Exit fullscreen mode

At this point we can install WiRL without any issues:

> blocks install wirl
Enter fullscreen mode Exit fullscreen mode

At this point I think you've got the idea. As we saw with WiRL, the more complex packages (such as MCPConnect too) will automatically download their dependencies as well. Keep in mind, however, that if you uninstall them 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.
  update <package>       Update an installed package and recompile its dependents.
  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
Enter fullscreen mode Exit fullscreen mode

Conclusions

Blocks is currently at version 0.7.0. 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.

Top comments (0)