Projects

Identifying Projects

Dado enhances the concept of project defined by Acre. Most importantly, Dado adds a URL parameter to the Acre configuration file. This project URL will generally be a GitHub URL (or any similar service). It identifies the project, and of course locates it on the internet. From the point of view of dependency management, the name and path of the project folder as it happens to be on the local storage is irrelevant to identifying the project (though obviously the project folder should be somewhat eponymously named.) The URL is added to the Acre config file by the ]DadoTools.AddRemotecommand, which associates a local project with an new, bare repository.

The last two segments of the URL implicitly define a project group and project name. For example, if the project URL is "https://github.com/Dyalog/Dfns", then the project name is Dfns and the project group is Dyalog. The configuration parameters Name and Group may be used to explicitly override these values (which should only be done if there is good reason). The project group and name uniquely identify a package, and the full URL is just used to locate it on the internet.

Project Namespace

In general, a project should be portable. That is, it should not matter where it is instantiated in the namespace tree, or even what the name of the namespace is, or indeed if it is in a named-namespace as opposed to an anonymous space. New projects should always strive for portability. A project must be portable in order to allow multiple versions of the same project to operate in the same workspace. However, legacy applications are often not portable, and it is often not worth the effort to change them. Dado makes it easy to work with portable and non-portable projects.

The ProjectSpace parameter of the AcreConfig file determines where a project is instantiated. It defaults to the project name (#.[Name]). A dependency specification may have its own ProjectSpace parameter. It defaults to the ProjectSpace parameter in the target project configuration file (which in turn defaults to #.[Name]. In either case, the ProjectSpace parameter may be set to the special value '*', which is interpreted as #.[Group] _ [Name] _ [Version]. This guarantees a unique project space name, and allows multiple versions of the same project to operate in the same workspace.

Thus the consumer of a package, when specifying the dependency, has total control over where the package is instantiated.

Project API and Aliases

The API configuration parameter specifies the access point for the project, relative to the project space. It defaults to the project space itself. It may be specified as a namespace or any function that returns a namespace. Thus the project author determines the API and the consumer cannot change this. However, the consumer can specify an Alias when specifying a dependency. The alias is instantiated as a reference to the API of the dependency. The alias defaults to the project name. The alias is instantiated in the project root or in all sub-spaces, as determined by the Inject parameter of the dependency.

Project Namespace Structure

The Acre project namespace may be structured anyway you like. However, following certain conventions allows AcreTools to do a lot for you. Generally, at a minimum, you should create at least one level of namespaces if just to separate tests from main code. Thus even the simplest utility project would have something like Main and Tests in the project root.

By convention, Dado recognizes some addtional specific namespaces:

UCMD: If your project is a User Command, then the project root space UCMD defines the List, Help, and Run functions. There may be additional support functions in here as well.

The /dist folder contains the results of doing a build. It should have an entry in the .gtignore file. This folder is entirely deleted and recreated by ReleaseNewVersion and Build commands. It will look like:

/dist/Package
/dist/Application
/dist/ReleaseNotes
/dist/ReleaseArtifacts