DepCharge Documentation

The DepCharge project is a set of MATLAB best practices, along with the DepCharge utility, which enables these best practices. Much of the effort revolves around compensating for deficiencies in Matlab's handling of packages and namespaces, particularly nested namespaces.

---

DepCharge Matlab dependency manager key features:

• In project deplist.json file specifies all project dependencies and how to get them.

• Dependencies managed automatically

• Source dependencies from git (commit/branch/tag) or URL or zip

  • verify_and_warn is an alternative mode for when using a dependency already on the path is preferable.

• Store Dependencies in local project _deps/ folder OR in global store.

• Add dependencies to the path

  • verify dependency is on the path (important for URL based)
  • (optionally) verify correct version

• Recursive project dependency management. Solves a key deficiency of Git Submodules, namely handling multiple dependencies with the same dependencies. When multiple dependencies have the same sub-dependency, redundant cloning is avoided.

---

Page Index

Theory

• MATLAB Project Organization Approaches

• MATLAB Best Practices according to DepCharge

  • Project folder layout
  • Project dependency handling

• user_stories

• general discussion(needs editing)

• The Trouble with MATLAB Packages

Implementation

• DepCharge Tool Design and Implementation

• Dependency configuration: deplist.json readme

  • deplist.json

  • depcharge_schema.json

---

Original Discussion

[toc]

---

The Problem

Library design in MATLAB is a struggle. As developers we are encouraged to write reusable code, but in MATLAB, once we've written good, reusable code, we are then faced with a variety of dilemmas which punish our good behavior.

Perhaps we're working on the Alpha project when we created a utility which automatically tiles figures on a designated screen or portion of a screen. This utility saves us time during analysis, and it saves time during coding. It provides a better workflow, and is generally useful.

In fact, our Utility would be very useful on a unrelated project Beta, with a different team. We copy the Utility into the Beta project. For better organization and to avoid name collisions, both projects exist within package folders, +alpha and +beta respectively. Unfortunately, this means that all the internal function calls in our utility will have to have their names changed. +alpha.fig_utility.* will have to change to +beta.fig_utility.* Our Beta teammates appreciate the new utility and begin adding features and fixing bugs. Now our codebases are diverging.

To avoid code duplication and missed bug fixes, we decide to move the fig_utility package to a new repository for unified maintenance. Once again, every function call must have its signature modified, since Matlab has no way to indicate that a block of code is within a namespace. There is disagreement here, however, because although this split may theoretically improve some maintenance issues, it creates new ones. Namely, it makes installing the project Alpha or Beta more complicated, as now fig_utility and alpha have to be downloaded and added to the path separately. What may have been easy to download and run before now becomes somewhat of a project, and may no longer be worth the trouble to some users.

To ease installation somewhat, git submodules are utilized. This

• What package name should I use? Hard to change.
  • Deeply nested packages get used to simplify delivery and installation and avoid modifying the path. However, these lengthen calls everywhere, and make separating sub-packages challenging, sometimes requiring significant manual work.
• Should I separate general utilities into stand alone packages
• Library/Package/Repository Organization
• Automatic Dependency installation

Alternative Solutions

Git Submodules

Tom M used these with success for a while.

Works ok for A -> U, but less so for A -> U & B , B -> U

---
title: Entangled Dependencies
---
flowchart LR
	A --> U & B
    B --> U

Matlab Projects

Could be part of the solution implementation, or not. 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 Implementation

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

DepCharge Tool Design and Implementation