tool_implementation - depcharge-org/depcharge GitHub Wiki

DepCharge Implementation

The Implementation challenges can be broken into a number different parts, each with its own trade offs.

Installation of DepCharge

It would be nice if no installation was required, but this isn't likely. Even cmake has to be installed before it can be used. Could be a Matlab toolbox.[^1][^2][^3]

The best we could do is make installation quick and easy.

Configuration file format

  • m-file function which returns a matlab structure
    • Somewhat easier to include a function handle to enable arbitrary setup behavior
  • json file which is convertible to a matlab structure
    • More generic. Clearly a data file. Could still provide a relative path to a matlab function for extra setup customizations.

Dependency Configuration Options

  • Get Dependency via git

    • store in project dependencies folder
    • store in system dependencies folder

  • Get Dependency via local URL

    • add URL to path
    • copy from URL to local dependencies folder

  • Get Dependency via local URL

    • add URL to path
    • copy from URL to local dependencies folder

  • Verify package is on path

    • Check if package is already on the path
    • Check if package is the right version
    • Fallback: Get Dependency via another option

Misc

  • DepCharge global dependency library

    • Is this desired as an option? (Probably)
    • Is the location static or configurable?
      • ~/my documents/depcharge_library
      • Could a matlab toolbox installation provide space for a library? Probably a bad idea, since the library will be associated with a version of matlab, which could change and orphan the files.

  • DepCharge static configuration location

    • matlab preferences (getprefs setprefs)
    • project specific ./.depcharge/ folder is possible

  • Handling path, changing and restoring path.

    • Should probably not ever store the path, so as to allow changes to be reverted by restarting matlab. DepCharge changes the path as needed programmatically anyhow.

  • Must all dependencies have a top level package?

    • Well no, for compatibility with the many tools on the Mathworks File Exchange which don't have package folders. However, this kind of namespace pollution should be discouraged.
    • providing a top level package may be a key way for determining if a dependency is already on the path. Without this, it may be difficult to detect that the dependency is available. This might not be too bad, if a copy of the dependency is known to the repo, and is added to the top of the path.
    • A custom function may be required to detect whether a dependency without a package exists on the path. If this were missing or optional, it would be hard to determine if the dependency was available or if it needed maintenance.

  • Template for handling problematic dependencies

    • Elsewhere the possibility of the deplist.json specifying a custom installation script was mentioned. Another idea would be to provide a +project/+depcharge/dependency1.m class for problem dependencies. This class might inherit from a superclass like depcharge.DependencyTool which provides a set of method which can be defined to provide a variety of functions, such as: detecting if the library is on the path, detecting library version, installing the library, etc.
    • This system should allow overriding default behaviors, such as adding a dependency to the path. It could be that a more subtle system for path management is required when adding poorly designed dependencies, such as special wrappers and function handles.

  • Support for conflicting dependencies already on the user's path.

    • If a user already has package of the same name as a dependency on the path,

  • Location of _deps and/or .depcharge/ folder(s) and deplist.json file.

    • deplist.json will be located at /project_name/+project_name/+depcharge/deplist.json
    • At least notionally the deplist.json could have been an m-file, and so it starts to make more sense to keep this file out of the project root, since that will be on the global namespace. Less critical if we're using a json file since it will probably be referred to by file path.
    • The assumption is that the parent folder of the +package folder is also part of the repo, and is an appropriate place to clone dependency libraries. Is this a safe assumption? Should it be confirmed in some way?

  • Matlab Projects - Probably not part of the solution. I need to look into Matlab Projects further and make some demos, but so far they look fairly flexible, but they don't seem to enforce good behavior either. If Projects turn out to be part of the solution, they will be mediated by a set of best practices.

  • depcharge execution. How is this done? Since you don't change a directory to a package directory, how is the top level package specified? Does the user run e.g. depcharge.update() and then select the top level package in a dialog box? Or should they provide a script to run, like +package/depcharge.m or +package/+depcharge/update.m which can be run to update the dependencies?

    • /project_name/+project_name/+depcharge/update.m seems like a good approach. The update.m could probably be a one liner, just calling a toolbox function which determines where it was called from. A proof of concepts has been created here.

  • The configuration field version could be optional. If it is used, some other option will have to specify HOW to determine the version of the dependency, whether by tag name, or by a function inside the dependency.

References

[^1]:Mathworks (2024, June 10). MATLAB Toolbox Best Practices. github.com. https://github.com/mathworks/toolboxdesign [^2]:Mathworks (2024, June 10). Climate Data Store Toolbox. github.com. https://github.com/mathworks/climatedatastore [^3]:Mathworks (2024, June 10). matlab.addons.toolbox.packageToolbox. matlab.com. https://www.mathworks.com/help/matlab/ref/matlab.addons.toolbox.packagetoolbox.html#d126e968897