Using Dyalog Link to Keep APL Source in Git

Problem: version‑controlling APL code

Dyalog workspaces are binary files. When you save a workspace you cannot diff, review, or branch the individual functions or variables that make up your application. Teams that rely on Git for code review and continuous integration therefore need a way to expose APL source as plain text.

Takeaway: Dyalog Link creates a round‑trip mapping

When Link is enabled (⎕LINK ← 1) each namespace, function, or variable is stored as a .dal file in a folder tree you define with ⎕LINKPATH. Changes made in the APL session are written to disk instantly, and external edits to .dal files are loaded back into the workspace on the next Link refresh. This lets you treat .dal files like any other source code while still working interactively in Dyalog.

Setting up Link

1. Choose a directory that your user can write to (e.g., a project folder under version control).
2. In a Dyalog session set the path:

   ⎕LINKPATH ← '/home/user/myproject/link'

3. Activate Link:

   ⎕LINK ← 1

After these steps the Link system creates a hidden database (⎕LINK) that tracks which objects correspond to which .dal files. If you later delete or corrupt that database you must re‑link the workspace (set ⎕LINK ← 0 then ⎕LINK ← 1) to restore synchronization.

Worked example: adding a function and editing it externally

Assume you have an empty workspace and the Link path from the previous section.

1. Define a simple function in the session:

   ∇foo←{⍵×2}∇

2. Link automatically writes the source to /home/user/myproject/link/foo.dal. You should see a file containing exactly the lines you entered, including the ∇ delimiters and any comments.
3. Edit the .dal file with your favourite editor, changing the multiplier to 3:

   ∇foo←{⍵×3}∇

   Save the file.
4. Refresh Link to pull the change back into the workspace. You can either toggle Link off and on or call the refresh function:

   ⎕LINK ← 0
   ⎕LINK ← 1

   or

   ⎕LINK REFRESH

5. Now invoke the function: foo 4 should return 12, confirming that the external edit took effect.

This round‑trip demonstrates how Link keeps the workspace and the file system in sync without manual export/import steps.

Trade‑offs and limitations

• Binary objects are not versioned. Compiled DLLs, GUI resources, or any non‑APL data stored in the workspace must be handled separately (e.g., checked in as binary assets or rebuilt as part of your CI pipeline).
• Initial setup can be confusing. You must set ⎕LINKPATH before activating Link; otherwise Link will refuse to start with a VALUE ERROR. Accidentally deleting the link database breaks synchronization until you re‑link.
• Version requirement. Link relies on the ⎕LINK system variable and associated file‑watcher, which were introduced in Dyalog 14.0. Earlier releases (e.g., 13.1) will raise a SYNTAX ERROR when you try to assign ⎕LINK, so teams on older versions need to continue using manual ⎕SAVE/⎕LOAD workflows.

Actionable closing steps

To start using Link in a real project:

1. Create a folder for your Link files and add it to your Git repository (e.g., git add link).
2. Set ⎕LINKPATH to that folder and activate Link in each developer’s workspace.
3. Commit the initial .dal files; thereafter, any change made in the session or edited externally will appear as a normal Git diff.
4. In your CI pipeline, run the Dyalog session with Link enabled, run your tests, and optionally pack the workspace for deployment.

By treating .dal files as first‑class source artifacts you gain the benefits of code review, branching, and automated testing while retaining the interactive power of Dyalog APL.