MATLAB Community

MATLAB, community & more

What Is a Toolbox? New Guidelines for Authors

The File Exchange provides access to more than 46,000 free MATLAB projects. For 33,854 of these projects, the authors included the word "toolbox" in the title. "Toolbox" is clearly a useful designation in the MATLAB community! But what exactly IS a toolbox? It's always been a little vague. The closest thing we've had to a universal definition is this: a folder containing some related and potentially useful MATLAB files. This definition applies to everything from a sophisticated commercial product to a couple of modest utilities tossed into a folder. The salient point about a toolbox is that it is useful as an ensemble, perhaps only to you but probably to others as well. A toolbox is something that one might distribute.

Let's try to clarify things here. Consider the words project and toolbox. What is the difference?

A project is the entirety of the thing that you work on. These days, it often lives in a GitHub repository (so "project" and "repo" are sometimes used interchangeably). A toolbox is the thing you distribute to people who will then install and use it. So toolboxes derive from projects, but in general they aren't the same thing. A simple working project might be identical with its distributable toolbox. But as you add tests and other supporting material that won't ship with the toolbox, the project becomes the larger containing entity.

Here's how I sometimes picture it: the project is the garage and the toolbox is the car.

Now let me put on top of this picture some of the related words we use.

That's the basic idea of what a toolbox is. But let's zoom in a little. What should a modern standard toolbox look like?

For years we've been fielding requests about what constitutes a good toolbox. People want to know: How should I organize my toolbox code? How can I avoid the common pitfalls of distributing code? How can I encourage others to collaborate with me?

To answer these questions, we recently rolled out guidance on MATLAB Toolbox Best Practices. You can read all the details as published in this GitHub repo:

mathworks/toolboxdesign: Best practices for creating MATLAB toolboxes.

Or if you prefer, you can browse through this simple example instance of a standard toolbox, the Arithmetic Toolbox.

mathworks/arithmetic: Example toolbox created to showcase MATLAB Toolbox Best Practices.

Here is a short list of things we recommend.

  • use GitHub
  • include a README
  • make it a MATLAB Project
  • put all the "working code" into a toolbox/ subfolder
  • package with MLTBX files
  • create examples with Live Scripts (MLX files)
  • create tests that can be run using GitHub Actions

We don't claim you have to do all these things in order to be a good person. These are conventions that we recommend. If you follow this advice (or even just some of it), it will be easier for others to find and use your code. The tools you create will have more reach and more impact.

I'll close by observing that this is an early version of a living standard, so you can expect it to evolve over time. In fact, we hope you will help us evolve it by opening issues or participating in discussions. We hope it will be useful to you as you make and share tools in MATLAB.

  • print


要发表评论,请点击 此处 登录到您的 MathWorks 帐户或创建一个新帐户。