Building a Magik project template with Emacs Projectile

A consistent project skeleton removes much of the repetitive setup involved in Magik development. Instead of recreating folders, configuration files, documentation, and test conventions for every GE Smallworld job, you can let Emacs Projectile generate a reliable starting point in seconds.

For Australian development teams, this is particularly useful when work is distributed between Sydney, Melbourne, Brisbane, Perth, and client sites. A shared template helps consultants, in-house developers, and contractors begin with the same assumptions, even when projects involve different environments, databases, transport networks, or release schedules.

Why a Magik template is worth building

Magik applications often grow around a substantial Smallworld configuration, custom methods, database definitions, and operational scripts. Without a standard layout, related files can end up scattered across personal workspaces. A new developer may spend the first day locating source code, test data, documentation, and deployment notes rather than understanding the application.

A Projectile template gives each project a predictable root directory. It can include a starter README, a source directory, test fixtures, configuration examples, and a place for technical decisions. Projectile then treats the generated directory as a project, making commands such as searching, compiling, opening buffers, and switching between files available immediately.

The template should establish conventions without pretending that every Magik system is identical. A utility mapping project may need data-loading scripts, while a council asset-management application may require integration notes and privacy controls. Keep the structure stable, but leave domain-specific details for the project’s own configuration.

Preparing Emacs and Projectile

Install Projectile through your preferred package manager, such as package.el, straight.el, or use-package. A straightforward configuration might look like this:

(use-package projectile
  :ensure t
  :init
  (projectile-mode +1)
  :bind-keymap
  ("C-c p" . projectile-command-map))

The exact key bindings are a matter of taste. The important point is that Projectile should be enabled in the Emacs session used for Magik work. Add your normal Magik editing, indentation, completion, and debugging packages alongside it rather than embedding every personal preference in the project template.

Projectile identifies projects through common markers and project files. A .projectile file at the root is useful when the directory does not contain a recognised build marker. It can also contain paths that should be included or excluded during project searches. For a Magik codebase, this lets you omit generated exports, large logs, local database files, or imported datasets from routine searches.

Before creating a template, test the workflow in an ordinary sample directory. Open a Magik source file, run projectile-find-file, search with projectile-grep, and confirm that the detected root is the directory you expect. Correct root detection matters more than an elaborate template because every navigation and search command depends on it.

Designing the project directory

A practical starting layout might be:

magik-project/
├── .projectile
├── README.md
├── .gitignore
├── src/
├── test/
├── config/
├── scripts/
├── docs/
└── data/
    └── sample/

Place production Magik code under src/, automated or repeatable checks under test/, and environment-specific settings under config/. The scripts/ directory can hold import, export, build, or deployment helpers. Keep data/sample/ restricted to synthetic or non-sensitive material so that developers can run examples without receiving a copy of a client database.

Use the README to explain how to open the project, which Smallworld version is required, how to configure the development environment, and how to run the standard checks. A short docs/decisions.md file can record why a collection, method naming convention, or database strategy was selected. This saves future developers from rediscovering the reasoning behind an implementation.

The .gitignore file deserves careful attention. Ignore editor backups, compiled artefacts, local credentials, temporary exports, and logs, but do not blindly exclude files that operations staff need for deployment. Australian organisations frequently exchange files with external consultants and managed service providers, so an accidental commit of a connection string or customer extract can create a serious incident.

Defining a Projectile template

Projectile stores project templates as an association between a template name and a directory containing its starter files. The precise option name or command prompt can vary with the Projectile version, so check the documentation installed with your package. A common configuration has this shape:

(setq projectile-project-templates
      '(("magik" . "~/src/project-templates/magik")
        ("default" . "~/src/project-templates/default")))

Create the template directory outside any active project, then populate it with the folders and files described above. From Emacs, invoke projectile-create-project and select the Magik template. Projectile copies the skeleton into the destination directory and opens it as a project.

Some teams prefer one general template with a magik subdirectory; others maintain separate templates for application development, data migration, and maintenance work. Begin with one focused option. A template that asks developers to delete half its contents is less useful than a modest template that is ready to use.

It is also sensible to include placeholder files where an empty directory would otherwise disappear from version control. A small .gitkeep file inside test/fixtures/ or data/sample/ communicates the intended layout. Use meaningful placeholder names, though, because generic files can be mistaken for real configuration.

Making the template useful for Magik

Projectile handles project navigation, not Magik semantics. The template becomes genuinely valuable when it works with the rest of your Emacs environment. Configure Magik mode, method navigation, code folding, object inspection, and debugging so that opening a generated project immediately provides the expected editing experience.

Project-local settings can be kept in a controlled .dir-locals.el file. For example, the file might select a particular major mode or define project-specific variables:

((magik-mode
  (magik-indent-offset . 2))
 (nil
  (projectile-project-compilation-cmd . "scripts/check-project")))

Only include settings that are safe and portable. A local path such as /Users/alex/Smallworld or a Windows drive letter should not be copied into every new project. Instead, document machine-specific variables in the README or load them from an ignored local file.

Add useful editor commands to the project documentation. Developers should know how to locate a method, search all Magik sources, fold a large method, inspect an object, and start a debugging session. A concise command reference can be more helpful than a long general Emacs guide. For examples of keeping technical experiments separate from production documentation, even an unrelated web example such as a roulette betting example can be placed in a scratchpad or research note rather than mixed into the application README.

Accounting for Australian teams and clients

Australian projects often involve a mix of permanent staff, contractors, and specialist consultants. A Sydney-based developer may work with a Melbourne product team and a Perth operations group, while a regional council may rely on a small local IT department. Record the expected time zone, support hours, and release window in the README, especially when daylight saving affects coordination between eastern states and Western Australia.

Templates should also reflect local compliance requirements. If sample records contain names, addresses, property information, or contact details, treat them carefully under the Privacy Act 1988 and the Australian Privacy Principles. Use fabricated identifiers in fixtures, document the source of any imported data, and make it obvious which files must never be committed. Privacy controls belong in the project workflow rather than being left to individual judgement.

Commercial work needs similar discipline. A consulting template can include a docs/acceptance.md file covering scope, test evidence, deployment responsibilities, and handover notes. This supports clearer delivery under the Australian Consumer Law and reduces misunderstandings about whether a defect, a change request, or an environmental problem is being addressed.

The local market also influences technical priorities. Australian utilities, councils, transport agencies, and mining organisations commonly manage large spatial datasets and long-lived systems. A useful template therefore records coordinate-system assumptions, data refresh procedures, backup expectations, and operational contacts. It should remain neutral about the client while making these recurring concerns visible from the first commit.

Sharing and maintaining the skeleton

Store the template in its own Git repository or in a controlled directory that is backed up and reviewed. Give it a README explaining how to register the template with Projectile, how to create a project from it, and which files are deliberately placeholders. Tag stable versions if several teams use the skeleton, so an existing project can continue using its original assumptions while new work adopts improvements.

Review the template after each project rather than adding every local workaround immediately. A change belongs in the shared skeleton when it has appeared repeatedly, is easy to explain, and does not depend on one customer’s infrastructure. For example, a standard test layout is a good candidate; a particular client’s database alias is not.

Keep a small maintenance checklist. Confirm that the Emacs configuration still works, template files contain no credentials, ignored files behave correctly, and the generated project is recognised by Projectile. Test the README by asking someone unfamiliar with the repository to create a project and perform the first routine task. Their friction will reveal missing instructions quickly.

If the team uses continuous integration, add a lightweight validation job for the template repository itself. It can check required files, inspect shell scripts for obvious errors, and verify that prohibited sample data is absent. The goal is confidence, not an elaborate release process.

Create the template repository, register it with Projectile, and generate a trial Magik project today. Populate the first version with a clean directory layout, safe sample data, a practical README, and the commands your team uses most often. Once the workflow feels natural, place the template under review and make it the default starting point for the next Australian Magik engagement.