deplist_file_readme - depcharge-org/depcharge GitHub Wiki

Creating a deplist.json Configuration File

The deplist.json file is used to specify dependencies for your Matlab project when using the DepCharge dependency manager. This README explains how to create and structure this file.

Basic Structure

The deplist.json file is a JSON object with the following top-level fields:

  • project_name: (Required) The name of your project.
  • version: (optional) The version of your project.
  • dependencies: (Required) An array of dependency objects.
  • allow_later_versions: (Optional) Boolean to allow later versions of dependencies.
  • recursive_dependencies: (Optional) Boolean to resolve dependencies recursively.

Specifying Dependencies

Each dependency in the dependencies array is an object with the following fields:

  • name: (Required) The name of the dependency.
  • package: (Optional) The name of the top level package (without +)
  • type: (Required) The type of the dependency source. Can be "git", "path", or "zip".
  • git_url: (Required for "git" and "zip" types) The URL of the git repository or zip file.
  • git_tag: (Required for "git") The commit hash, branch name, or tag to pull.
  • path: (Required for "path" type) The local path to the dependency.
  • version: (Optional) The version of the dependency required. This version is either determined using
  • require_exact_version: (Optional) Boolean indicating if the exact version is required.
  • installation: (Optional) Can be "local" or "global". Defaults to "local".`
  • customer_handler: (Optional) Path to a custom handler class.

Custom Dependency Handlers

For dependencies with special requirements, you can create custom handler classes. These classes should inherit from the DependencyHandler base class and can override the following methods:

  • getVersion(): Retrieve the version of the dependency. If the dependency uses DepCharge, then this will be the value of the top level version, or null. If it is not DepCharge, could could be written to grab a version file from the project, or a last commit date from the git repo.
  • getProjectRoot(): Get the path to the dependency's project root. This defaults to the path to the dependency download folder, with the git repo name or dependency name.
  • isOnPath(): Check if the dependency is on the MATLAB path. If the package is specified, then existp() is used to search for that package. If the package is not specified, determination would be impossible without a custom function. For instance, the existence of a a unique function or class on the path could be searched for.
  • setupPath(): Support adding the path for this dependency. The default behavior is to add the project root to the path. However, this behavior can be overridden.
  • setupDependencies():
  • executeAfterDownload(): Perform actions after the dependency is downloaded.
  • executeBeforeUse(): Perform actions before the dependency is used.
  • cleanUp(): Perform cleanup actions when the dependency is no longer needed.

Custom handler classes should be placed in the +project/+depcharge/ directory of your project.

Implementation Details:
Whether specialized or not, and instance of the DependencyHandler (or children) will be created for each dependency. An array (or map) of these handlers will be maintained as dependencies are loaded recursively. Note that while a top level DepCharge update will create a fresh Map of DependencyHandlers, lower level dependencies will receive a reference to the map which they can add to. The cache location will be at the top level project, not within the lower level projects.

How will the map keys deconflict dependencies? If the keys were package names this would be fine. With package names optional, a combo of name and package name could be used. Or a combo of name, package name, and dependency path? The fact is that if the package name is blank means more likelyhood of name collisions, which makes it very important that there are not ALSO mismatching dependency names, because then the dependency will be on the path twice. Actually should still work despite shadowing. So Name+Path for the keys might be fine.

The dependency objects (or a containing object... DepManager) should contain a string array with a log of status, error, and warning messages. The DependencyHandler objects might also need a similar log to record conflicts between version requirements of different dependencies.

Another potential source of trouble is when the same dependency is used twice, but with different specializations. Probably the best approach is to record a warning in the log and use the first specialization. Otherwise, you could use the "requires_exact_version" as a tie breaker, and if only one has this set, you could let that layer have its preference on that dependency.

It would be a hassle, though not strictly impossible, to support two versions of a dependency at the same time. Probably best avoided.

Example

Here's an example deplist.json file:

{
  "project_name": "ExampleProject",
  "version": "1.0.0",
  "dependencies": [
    {
      "name": "UtilityLibrary",
      "type": "git",
      "url": "https://github.com/example/utility-library.git",
      "version": "tag:v2.0",
      "required_version": true,
      "installation": "local"
    },
    {
      "name": "LocalTool",
      "type": "path",
      "path": "../LocalTool",
      "installation": "local"
    },
    {
      "name": "FileExchangeTool",
      "type": "zip",
      "url": "https://www.mathworks.com/matlabcentral/fileexchange/download.zip",
      "installation": "global"
    }
  ],
  "allow_later_versions": false,
  "recursive_dependencies": true
}