├── License.txt ├── README.md ├── SECURITY.md └── images ├── PackagingTool.jpg └── cc-by-40.png /License.txt: -------------------------------------------------------------------------------- 1 | MATLAB Toolbox Best Practices © 2023 by The MathWorks, Inc. 2 | 3 | Attribution 4.0 International 4 | 5 | ======================================================================= 6 | 7 | Creative Commons Corporation ("Creative Commons") is not a law firm and 8 | does not provide legal services or legal advice. Distribution of 9 | Creative Commons public licenses does not create a lawyer-client or 10 | other relationship. Creative Commons makes its licenses and related 11 | information available on an "as-is" basis. Creative Commons gives no 12 | warranties regarding its licenses, any material licensed under their 13 | terms and conditions, or any related information. Creative Commons 14 | disclaims all liability for damages resulting from their use to the 15 | fullest extent possible. 16 | 17 | Using Creative Commons Public Licenses 18 | 19 | Creative Commons public licenses provide a standard set of terms and 20 | conditions that creators and other rights holders may use to share 21 | original works of authorship and other material subject to copyright 22 | and certain other rights specified in the public license below. The 23 | following considerations are for informational purposes only, are not 24 | exhaustive, and do not form part of our licenses. 25 | 26 | Considerations for licensors: Our public licenses are 27 | intended for use by those authorized to give the public 28 | permission to use material in ways otherwise restricted by 29 | copyright and certain other rights. Our licenses are 30 | irrevocable. Licensors should read and understand the terms 31 | and conditions of the license they choose before applying it. 32 | Licensors should also secure all rights necessary before 33 | applying our licenses so that the public can reuse the 34 | material as expected. Licensors should clearly mark any 35 | material not subject to the license. This includes other CC- 36 | licensed material, or material used under an exception or 37 | limitation to copyright. More considerations for licensors: 38 | wiki.creativecommons.org/Considerations_for_licensors 39 | 40 | Considerations for the public: By using one of our public 41 | licenses, a licensor grants the public permission to use the 42 | licensed material under specified terms and conditions. If 43 | the licensor's permission is not necessary for any reason--for 44 | example, because of any applicable exception or limitation to 45 | copyright--then that use is not regulated by the license. Our 46 | licenses grant only permissions under copyright and certain 47 | other rights that a licensor has authority to grant. Use of 48 | the licensed material may still be restricted for other 49 | reasons, including because others have copyright or other 50 | rights in the material. A licensor may make special requests, 51 | such as asking that all changes be marked or described. 52 | Although not required by our licenses, you are encouraged to 53 | respect those requests where reasonable. More considerations 54 | for the public: 55 | wiki.creativecommons.org/Considerations_for_licensees 56 | 57 | ======================================================================= 58 | 59 | Creative Commons Attribution 4.0 International Public License 60 | 61 | By exercising the Licensed Rights (defined below), You accept and agree 62 | to be bound by the terms and conditions of this Creative Commons 63 | Attribution 4.0 International Public License ("Public License"). To the 64 | extent this Public License may be interpreted as a contract, You are 65 | granted the Licensed Rights in consideration of Your acceptance of 66 | these terms and conditions, and the Licensor grants You such rights in 67 | consideration of benefits the Licensor receives from making the 68 | Licensed Material available under these terms and conditions. 69 | 70 | 71 | Section 1 -- Definitions. 72 | 73 | a. Adapted Material means material subject to Copyright and Similar 74 | Rights that is derived from or based upon the Licensed Material 75 | and in which the Licensed Material is translated, altered, 76 | arranged, transformed, or otherwise modified in a manner requiring 77 | permission under the Copyright and Similar Rights held by the 78 | Licensor. For purposes of this Public License, where the Licensed 79 | Material is a musical work, performance, or sound recording, 80 | Adapted Material is always produced where the Licensed Material is 81 | synched in timed relation with a moving image. 82 | 83 | b. Adapter's License means the license You apply to Your Copyright 84 | and Similar Rights in Your contributions to Adapted Material in 85 | accordance with the terms and conditions of this Public License. 86 | 87 | c. Copyright and Similar Rights means copyright and/or similar rights 88 | closely related to copyright including, without limitation, 89 | performance, broadcast, sound recording, and Sui Generis Database 90 | Rights, without regard to how the rights are labeled or 91 | categorized. For purposes of this Public License, the rights 92 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 93 | Rights. 94 | 95 | d. Effective Technological Measures means those measures that, in the 96 | absence of proper authority, may not be circumvented under laws 97 | fulfilling obligations under Article 11 of the WIPO Copyright 98 | Treaty adopted on December 20, 1996, and/or similar international 99 | agreements. 100 | 101 | e. Exceptions and Limitations means fair use, fair dealing, and/or 102 | any other exception or limitation to Copyright and Similar Rights 103 | that applies to Your use of the Licensed Material. 104 | 105 | f. Licensed Material means the artistic or literary work, database, 106 | or other material to which the Licensor applied this Public 107 | License. 108 | 109 | g. Licensed Rights means the rights granted to You subject to the 110 | terms and conditions of this Public License, which are limited to 111 | all Copyright and Similar Rights that apply to Your use of the 112 | Licensed Material and that the Licensor has authority to license. 113 | 114 | h. Licensor means the individual(s) or entity(ies) granting rights 115 | under this Public License. 116 | 117 | i. Share means to provide material to the public by any means or 118 | process that requires permission under the Licensed Rights, such 119 | as reproduction, public display, public performance, distribution, 120 | dissemination, communication, or importation, and to make material 121 | available to the public including in ways that members of the 122 | public may access the material from a place and at a time 123 | individually chosen by them. 124 | 125 | j. Sui Generis Database Rights means rights other than copyright 126 | resulting from Directive 96/9/EC of the European Parliament and of 127 | the Council of 11 March 1996 on the legal protection of databases, 128 | as amended and/or succeeded, as well as other essentially 129 | equivalent rights anywhere in the world. 130 | 131 | k. You means the individual or entity exercising the Licensed Rights 132 | under this Public License. Your has a corresponding meaning. 133 | 134 | 135 | Section 2 -- Scope. 136 | 137 | a. License grant. 138 | 139 | 1. Subject to the terms and conditions of this Public License, 140 | the Licensor hereby grants You a worldwide, royalty-free, 141 | non-sublicensable, non-exclusive, irrevocable license to 142 | exercise the Licensed Rights in the Licensed Material to: 143 | 144 | a. reproduce and Share the Licensed Material, in whole or 145 | in part; and 146 | 147 | b. produce, reproduce, and Share Adapted Material. 148 | 149 | 2. Exceptions and Limitations. For the avoidance of doubt, where 150 | Exceptions and Limitations apply to Your use, this Public 151 | License does not apply, and You do not need to comply with 152 | its terms and conditions. 153 | 154 | 3. Term. The term of this Public License is specified in Section 155 | 6(a). 156 | 157 | 4. Media and formats; technical modifications allowed. The 158 | Licensor authorizes You to exercise the Licensed Rights in 159 | all media and formats whether now known or hereafter created, 160 | and to make technical modifications necessary to do so. The 161 | Licensor waives and/or agrees not to assert any right or 162 | authority to forbid You from making technical modifications 163 | necessary to exercise the Licensed Rights, including 164 | technical modifications necessary to circumvent Effective 165 | Technological Measures. For purposes of this Public License, 166 | simply making modifications authorized by this Section 2(a) 167 | (4) never produces Adapted Material. 168 | 169 | 5. Downstream recipients. 170 | 171 | a. Offer from the Licensor -- Licensed Material. Every 172 | recipient of the Licensed Material automatically 173 | receives an offer from the Licensor to exercise the 174 | Licensed Rights under the terms and conditions of this 175 | Public License. 176 | 177 | b. No downstream restrictions. You may not offer or impose 178 | any additional or different terms or conditions on, or 179 | apply any Effective Technological Measures to, the 180 | Licensed Material if doing so restricts exercise of the 181 | Licensed Rights by any recipient of the Licensed 182 | Material. 183 | 184 | 6. No endorsement. Nothing in this Public License constitutes or 185 | may be construed as permission to assert or imply that You 186 | are, or that Your use of the Licensed Material is, connected 187 | with, or sponsored, endorsed, or granted official status by, 188 | the Licensor or others designated to receive attribution as 189 | provided in Section 3(a)(1)(A)(i). 190 | 191 | b. Other rights. 192 | 193 | 1. Moral rights, such as the right of integrity, are not 194 | licensed under this Public License, nor are publicity, 195 | privacy, and/or other similar personality rights; however, to 196 | the extent possible, the Licensor waives and/or agrees not to 197 | assert any such rights held by the Licensor to the limited 198 | extent necessary to allow You to exercise the Licensed 199 | Rights, but not otherwise. 200 | 201 | 2. Patent and trademark rights are not licensed under this 202 | Public License. 203 | 204 | 3. To the extent possible, the Licensor waives any right to 205 | collect royalties from You for the exercise of the Licensed 206 | Rights, whether directly or through a collecting society 207 | under any voluntary or waivable statutory or compulsory 208 | licensing scheme. In all other cases the Licensor expressly 209 | reserves any right to collect such royalties. 210 | 211 | 212 | Section 3 -- License Conditions. 213 | 214 | Your exercise of the Licensed Rights is expressly made subject to the 215 | following conditions. 216 | 217 | a. Attribution. 218 | 219 | 1. If You Share the Licensed Material (including in modified 220 | form), You must: 221 | 222 | a. retain the following if it is supplied by the Licensor 223 | with the Licensed Material: 224 | 225 | i. identification of the creator(s) of the Licensed 226 | Material and any others designated to receive 227 | attribution, in any reasonable manner requested by 228 | the Licensor (including by pseudonym if 229 | designated); 230 | 231 | ii. a copyright notice; 232 | 233 | iii. a notice that refers to this Public License; 234 | 235 | iv. a notice that refers to the disclaimer of 236 | warranties; 237 | 238 | v. a URI or hyperlink to the Licensed Material to the 239 | extent reasonably practicable; 240 | 241 | b. indicate if You modified the Licensed Material and 242 | retain an indication of any previous modifications; and 243 | 244 | c. indicate the Licensed Material is licensed under this 245 | Public License, and include the text of, or the URI or 246 | hyperlink to, this Public License. 247 | 248 | 2. You may satisfy the conditions in Section 3(a)(1) in any 249 | reasonable manner based on the medium, means, and context in 250 | which You Share the Licensed Material. For example, it may be 251 | reasonable to satisfy the conditions by providing a URI or 252 | hyperlink to a resource that includes the required 253 | information. 254 | 255 | 3. If requested by the Licensor, You must remove any of the 256 | information required by Section 3(a)(1)(A) to the extent 257 | reasonably practicable. 258 | 259 | 4. If You Share Adapted Material You produce, the Adapter's 260 | License You apply must not prevent recipients of the Adapted 261 | Material from complying with this Public License. 262 | 263 | 264 | Section 4 -- Sui Generis Database Rights. 265 | 266 | Where the Licensed Rights include Sui Generis Database Rights that 267 | apply to Your use of the Licensed Material: 268 | 269 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 270 | to extract, reuse, reproduce, and Share all or a substantial 271 | portion of the contents of the database; 272 | 273 | b. if You include all or a substantial portion of the database 274 | contents in a database in which You have Sui Generis Database 275 | Rights, then the database in which You have Sui Generis Database 276 | Rights (but not its individual contents) is Adapted Material; and 277 | 278 | c. You must comply with the conditions in Section 3(a) if You Share 279 | all or a substantial portion of the contents of the database. 280 | 281 | For the avoidance of doubt, this Section 4 supplements and does not 282 | replace Your obligations under this Public License where the Licensed 283 | Rights include other Copyright and Similar Rights. 284 | 285 | 286 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 287 | 288 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 289 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 290 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 291 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 292 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 293 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 294 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 295 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 296 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 297 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 298 | 299 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 300 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 301 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 302 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 303 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 304 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 305 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 306 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 307 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 308 | 309 | c. The disclaimer of warranties and limitation of liability provided 310 | above shall be interpreted in a manner that, to the extent 311 | possible, most closely approximates an absolute disclaimer and 312 | waiver of all liability. 313 | 314 | 315 | Section 6 -- Term and Termination. 316 | 317 | a. This Public License applies for the term of the Copyright and 318 | Similar Rights licensed here. However, if You fail to comply with 319 | this Public License, then Your rights under this Public License 320 | terminate automatically. 321 | 322 | b. Where Your right to use the Licensed Material has terminated under 323 | Section 6(a), it reinstates: 324 | 325 | 1. automatically as of the date the violation is cured, provided 326 | it is cured within 30 days of Your discovery of the 327 | violation; or 328 | 329 | 2. upon express reinstatement by the Licensor. 330 | 331 | For the avoidance of doubt, this Section 6(b) does not affect any 332 | right the Licensor may have to seek remedies for Your violations 333 | of this Public License. 334 | 335 | c. For the avoidance of doubt, the Licensor may also offer the 336 | Licensed Material under separate terms or conditions or stop 337 | distributing the Licensed Material at any time; however, doing so 338 | will not terminate this Public License. 339 | 340 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 341 | License. 342 | 343 | 344 | Section 7 -- Other Terms and Conditions. 345 | 346 | a. The Licensor shall not be bound by any additional or different 347 | terms or conditions communicated by You unless expressly agreed. 348 | 349 | b. Any arrangements, understandings, or agreements regarding the 350 | Licensed Material not stated herein are separate from and 351 | independent of the terms and conditions of this Public License. 352 | 353 | 354 | Section 8 -- Interpretation. 355 | 356 | a. For the avoidance of doubt, this Public License does not, and 357 | shall not be interpreted to, reduce, limit, restrict, or impose 358 | conditions on any use of the Licensed Material that could lawfully 359 | be made without permission under this Public License. 360 | 361 | b. To the extent possible, if any provision of this Public License is 362 | deemed unenforceable, it shall be automatically reformed to the 363 | minimum extent necessary to make it enforceable. If the provision 364 | cannot be reformed, it shall be severed from this Public License 365 | without affecting the enforceability of the remaining terms and 366 | conditions. 367 | 368 | c. No term or condition of this Public License will be waived and no 369 | failure to comply consented to unless expressly agreed to by the 370 | Licensor. 371 | 372 | d. Nothing in this Public License constitutes or may be interpreted 373 | as a limitation upon, or waiver of, any privileges and immunities 374 | that apply to the Licensor or You, including from the legal 375 | processes of any jurisdiction or authority. 376 | 377 | 378 | ======================================================================= 379 | 380 | Creative Commons is not a party to its public licenses. 381 | Notwithstanding, Creative Commons may elect to apply one of its public 382 | licenses to material it publishes and in those instances will be 383 | considered the “Licensor.” The text of the Creative Commons public 384 | licenses is dedicated to the public domain under the CC0 Public Domain 385 | Dedication. Except for the limited purpose of indicating that material 386 | is shared under a Creative Commons public license or as otherwise 387 | permitted by the Creative Commons policies published at 388 | creativecommons.org/policies, Creative Commons does not authorize the 389 | use of the trademark "Creative Commons" or any other trademark or logo 390 | of Creative Commons without its prior written consent including, 391 | without limitation, in connection with any unauthorized modifications 392 | to any of its public licenses or any other arrangements, 393 | understandings, or agreements concerning use of licensed material. For 394 | the avoidance of doubt, this paragraph does not form part of the public 395 | licenses. 396 | 397 | Creative Commons may be contacted at creativecommons.org. 398 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # MATLAB Toolbox Best Practices 2 | 3 | ![Version Number](https://img.shields.io/github/v/release/mathworks/toolboxdesign?label=version) ![CC-BY-4.0 License](https://img.shields.io/github/license/mathworks/toolboxdesign) 4 | 5 | You have a MATLAB® toolbox that you want to share with the world. We want to help. To do that, we want to convince you to use the MathWorks Toolbox best practices. It's a little bit of extra work with a big payoff. 6 | 7 | This is a continuously evolving document and some best practices may change in the future as MATLAB evolves. We encourage your feedback and suggestions for future revisions. Feel free to [open an issue](https://github.com/mathworks/toolboxdesign/issues) or [post to the discussions](https://github.com/mathworks/toolboxdesign/discussions). Your insights and feedback help us improve this document and make it even more useful for the community. Right now, we're focused on toolboxes that don't have derived files that require a build step, like MEX files or content-obscured files (P-Code). We plan to address those in the future. 8 | 9 | Being in a standard format makes it easier for other people to assess and take advantage of your work. Your work is more "legible," because it's in a familiar format. They know, for example, that they can always expect to find a helpful and thorough `README.md` file in the top folder. They also know that a good place to start learning how to use your toolbox will be the `gettingStarted.mlx` file. These and other best practices help your users build confidence that your toolbox is well built and ready to use. 10 | 11 | But the advantages go beyond helping your users. Standard formats also make it easier for you to maintain the toolbox. Tools and systems (such as automated testing on GitHub) will immediately know how to work. 12 | 13 | We use the term “toolbox” here to mean a collection of reusable MATLAB code that you want to share with other people. Toolboxes contain not just code files, but also data, apps, tests, and examples. Some toolboxes will be just a few files; others may be extensive and represent years of effort by multiple people. The guidelines we present can be adapted for toolboxes that are large or small, casual or sophisticated. We will step through a comprehensive example with many aspects. There’s no need to do everything all at once -- you can start with a few guidelines and adopt more as you go. 14 | 15 | To make it easier to follow, we’ve created a fictitious toolbox for doing basic arithmetic: The Arithmetic Toolbox on [GitHub](https://github.com/mathworks/arithmetic). We’ll use this throughout to show how to apply these design principles. If you'd like to explore a complete toolbox that uses this structure, visit the [Climate Data Store Toolbox](https://github.com/mathworks/climatedatastore). 16 | 17 | ## Topics 18 | 19 | * [Root Folder](#root-folder) 20 | * [Toolbox Folder](#toolbox-folder) 21 | * [Packaging and Releasing your Toolbox](#packaging-and-releasing-your-toolbox) 22 | * [Make your Toolbox more robust](#make-your-toolbox-more-robust) 23 | * [MATLAB Online and File Exchange badges](#open-in-matlab-online-and-file-exchange-badges-for-githubcom) 24 | 25 | ## Root Folder 26 | 27 | At the top level of your project is a folder or source repository, which we'll call the _root folder_. This folder has everything a developer needs to collaborate with you on your toolbox. When you are working in GitHub, this is the repository name, and will be the name of the folder when the repository is cloned. 28 | 29 | * To name the root folder of your toolbox, shorten the English name by removing the word "toolbox" and start with a letter. Use only letters, numbers, and underscores. For instance, if your toolbox is named "QuickerSim CFD Toolbox for MATLAB," the root folder might be named "quickerSimCFD." Following this naming convention will guarantee the validity of your toolbox in every operating system and source control system you use, eliminating the need to rename it in the future whenever you migrate to new systems. 30 | * Include a `README.md` file in the root folder. See [this article](https://medium.com/swlh/how-to-make-the-perfect-readme-md-on-github-92ed5771c061) for a good tutorial. Start with a short, user focused summary of the toolbox with installation instructions, and then point them to your `gettingStarted.mlx` file (see below). The rest of your `README.md` should be written for collaborators working on the toolbox, and how to contribute to it. It is a historical convention (more than 50 years!) that the file name be capitalized to make it stand out. 31 | * A `license.txt` file outlines how others can use, distribute, and change your code. Including a license file adds clarity and transparency for other people. Without a license, others may not be sure if they're allowed to use or change your code. 32 | * You should put images for your `README.md` file in an `images` folder to reduce clutter. 33 | * See [below](#make-your-toolbox-more-robust) for information on where to put tests, MATLAB projects, and automation files. 34 | 35 | Our example toolbox starts with a `README.md` with a single image, plus a `license.txt` file. 36 | 37 | ``` markdown 38 | arithmetic/ 39 | | README.md 40 | | license.txt 41 | └───images/ 42 | readmeImage.jpg 43 | ``` 44 | 45 | ## Toolbox Folder 46 | 47 | The _toolbox folder_ is where you store all the materials that you plan to share with your users, including code, apps, and examples. Storing these materials in a single folder makes it clear what is going to be distributed to users, and what is not. The folder is named `toolbox` and placed under the root folder. 48 | 49 | The structure of this folder depends on the size and complexity of your toolbox: 50 | 51 | * For projects with less than 20 functions or classes, put the documented functions that you expect users to call directly at the top level of the toolbox folder. 52 | * For larger projects, put the most commonly used functions and classes at the top level of the toolbox folder. Then, group additional specialized functions into folders by functionality. To keep things even more organized, consider using namespaces ([see below](#enhancing-your-toolbox)) to organize your functions and classes into logical groups. 53 | * Any supporting code should be put in an `internal` folder at the top level of the toolbox folder to make it clear that these functions are not intended for end users. If you have a lot of internal functions, consider creating subfolders to group them logically. 54 | 55 | We also recommend including in your toolbox folder: 56 | 57 | * A `gettingStarted.mlx` file at the top level of the toolbox folder that introduces your users to your toolbox and showcase important workflows. This file should give an overview of how to use your toolbox and highlight key functionality. 58 | * Examples are an effective way for users to learn how to use your toolbox. We recommend using MATLAB Live Scripts to show how to use different parts of your toolbox and including them in an `examples` folder under the toolbox directory. This makes it easier for users to explore and try out different code samples. 59 | 60 | Our example toolbox has: 61 | 62 | 1. A `gettingStarted.mlx` file at the top level of the toolbox folder 63 | 2. A function for users called `add.m`. 64 | 3. An `examples` folder with MATLAB Live Scripts showing different ways the toolbox can be used. 65 | 4. An internal function, `intToWord.m` that isn't intended for end users. 66 | 67 | ``` markdown 68 | arithmetic/ 69 | : 70 | └───toolbox/ 71 | | add.m 72 | | gettingStarted.mlx 73 | ├───examples/ 74 | | usingAdd.mlx 75 | └───internal/ 76 | intToWord.m 77 | ``` 78 | 79 | ### Enhancing your toolbox 80 | 81 | MATLAB offers various features to make your toolbox more intuitive and user-friendly. We recommend the following to improve the quality of your toolbox: 82 | 83 | * **Suggestions and Argument Validation:** To enhance your user's experience when using your functions, you can add an `arguments` block to create customized tab completion suggestions. This was introduced in R2019a. Additionally, MATLAB will verify the type, size, and values passed to your function, enabling users to call your function correctly. See the [Function Argument Validation documentation](https://www.mathworks.com/help/matlab/matlab_prog/function-argument-validation-1.html) for more information. If you need more control over tab completion, create a `functionSignatures.json` and place it in the same directory as the corresponding function or class. See the [custom suggestions and tab completion documentation](https://www.mathworks.com/help/matlab/matlab_prog/customize-code-suggestions-and-completions.html) for more information. 84 | 85 | * **Namespaces:** Namespaces (also known as Packages) provide a means to organize classes and functions and reduce the risk of two functions having the same name. See the [Namespaces documentation](https://www.mathworks.com/help/matlab/matlab_oop/scoping-classes-with-packages.html) for more information. 86 | 87 | * **MATLAB Apps:** MATLAB Apps are interactive graphical applications that allow users to do specific workflows in your toolbox. You package your MATLAB App into a single file (.mlapp) for easier distribution. Create an `apps` folder at the top level of your toolbox folder. When you package your toolbox, make sure to include your apps in the toolbox packaging dialog's apps section. This way, the users can easily access and run your apps after installation. See the [MATLAB apps documentation](https://www.mathworks.com/help/matlab/gui-development.html) for more information. 88 | 89 | * **Live Tasks:** Live Tasks are simple point-and-click interfaces that can be used inside a Live Script, starting in R2022a. They offer an interactive and intuitive approach for users to interact with your toolbox. Place your Live Task class in the `internal` folder in the toolbox folder, since users do not directly call this function. As part of the creation, you'll create a `liveTasks.json` file, which must go in a `resources` folder. See the [Live Tasks documentation](https://www.mathworks.com/help/matlab/develop-live-editor-tasks.html) for more information. 90 | 91 | Our example toolbox takes advantage of all these recommended features, providing a user-friendly experience: 92 | 93 | 1. An app called `arithmetic.mlapp` in the `apps` folder 94 | 2. Tab completion and argument validation for our functions 95 | 3. The secondary functionality `describe.add` in the `describe` namespace. These are grouped in the `+describe` folder. 96 | 4. A Live Task in the `internal` folder and its accompanying `liveTasks.json` file. 97 | 98 | ``` markdown 99 | arithmetic/ 100 | : 101 | └───toolbox/ 102 | | add.m 103 | | functionSignatures.json 104 | | gettingStarted.mlx 105 | ├───+describe/ 106 | | add.m 107 | ├───apps/ 108 | | arithmetic.mlapp 109 | ├───examples/ 110 | | usingAdd.mlx 111 | └───internal/ 112 | | addLiveTask.m 113 | | intToWord.m 114 | └───resources/ 115 | liveTasks.json 116 | ``` 117 | 118 | ## Packaging and Releasing your Toolbox 119 | 120 | To successfully share your toolbox with others, having a release strategy is crucial. This will help you keep track of which version of your toolbox your users have and make bug reporting more efficient. Additionally, it will ensure that your users are equipped with a stable and well-functioning version of your code. By implementing a release strategy, you can have better control over the distribution of your toolbox and ensure the best experience for your users. 121 | 122 | Sharing a MATLAB toolbox typically involves sharing a collection of .m files or combining them into a .zip file. However, we highly recommend a better approach - packaging your toolbox into a MATLAB Toolbox file (`.mltbx`) - for a more enhanced user experience. You can provide an icon for your toolbox, version number, and other information. They can easily discover, install, update, and uninstall your toolbox via the [Add-on Manager](https://www.mathworks.com/help/matlab/matlab_env/get-add-ons.html). 123 | 124 | For a full overview of toolbox packaging, see the [Create and Share Toolboxes](https://www.mathworks.com/help/matlab/matlab_prog/create-and-share-custom-matlab-toolboxes.html) section of the documentation. 125 | 126 | The information about your toolbox is stored in a toolbox packaging file. Confusingly, this file has a `.prj` extension -- the same as a MATLAB project file. These files are not interchangeable. Because of this, we recommend that you name your packaging file `toolboxPackaging.prj` and put it in the root folder. To make it clear which icon image file will be used, we recommend that you symmetrically name this file `toolboxPackaging.jpg` and put it in the `images` folder. These files should be under source control. 127 | 128 | Toolbox packaging files are created using the Toolbox Packaging Tool. In MATLAB, go to the home tab, drop the "Add-Ons" menu, and choose "Package Toolbox." 129 | 130 | ![Screenshot of Packaging Tool](images/PackagingTool.jpg) 131 | 132 | The MATLAB Toolbox file (`.mltbx`) created by the packaging tool should be placed in a folder named `release` under the root folder. Since this is a derived file, it should not be under source control. 133 | 134 | **What to include:** When you package, include all the contents in the toolbox folder, nothing else -- no exclusions, no extra stuff. Make sure that you include all your apps in the apps section of the packaging dialog. 135 | 136 | **Naming:** Give a suitable name to your toolbox, this is the name users will see in the Add-on manager. It is recommended that you use spaces in the toolbox name to make it more readable. The MATLAB Toolbox file that gets created in the build process will have the same name. Note that GitHub.com does not allow spaces in files added to a release, so before you upload, you will have to change the filename to make spaces into underscores. 137 | 138 | **Version:** Use semantic versioning. It helps your users plan and understand how much work they will have to do to update to your latest release. See the [Semantic Versioning Standard](https://semver.org/) for more information -- you really only need to read the summary. In the case of MATLAB, your "API" is the set of functions that your users use. 139 | 140 | Our example toolbox has chosen to use the name “Arithmetic Toolbox” in the Add-on Manager. 141 | 142 | ``` markdown 143 | arithmetic/ 144 | : 145 | | toolboxPackaging.prj 146 | ├───images/ 147 | │ readmeImage.jpg 148 | │ toolboxPackaging.jpg 149 | ├───release/ 150 | │ Arithmetic Toolbox.mltbx 151 | └───toolbox/ 152 | add.m 153 | : 154 | ``` 155 | 156 | Once a toolbox is packaged, there are multiple options to release your toolbox 157 | 158 | * Create a [GitHub release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) and link to [MATLAB File Exchange](https://www.mathworks.com/matlabcentral/fileexchange/). This lets you control what is delivered to users. Your toolbox will appear in the Add-on Explorer, and the latest released version will be installed. See [this post](https://www.mathworks.com/matlabcentral/discussions/highlights/132204-github-releases-in-file-exchange) for more info about how GitHub releases are shown in File Exchange. 159 | * Create a GitHub source repository and link to MATLAB File Exchange. When you do this, your latest code in GitHub is always used. 160 | * Post directly to MATLAB File Exchange 161 | * Copy the MATLAB Toolbox file (`.mltbx`) to a shared location for your users. They can just double-click it to install it. 162 | 163 | ## Make your Toolbox more robust 164 | 165 | To help you ensure that your toolbox is high-quality, performant, and reliable, MATLAB has several features to help. We'll introduce you to the ones we think are critical for toolbox authors. 166 | 167 | ### Tests 168 | 169 | Tests check the quality of your toolbox and help you build confidence that you have high quality releases. The [MATLAB Testing Framework](https://www.mathworks.com/help/matlab/matlab-unit-test-framework.html) provides support for testing your code. For users familiar with MATLAB, [Function-Based Unit Tests](https://www.mathworks.com/help/matlab/function-based-unit-tests.html) will be the most familiar. Place your tests under the `tests` folder in the root folder since tests are not usually shared with your users. If you host your toolbox on GitHub.com, you can use [GitHub Actions](https://github.com/matlab-actions/overview) created by MathWorks to qualify a change by automatically running the tests. 170 | 171 | Here's what our example toolbox looks like with tests: 172 | 173 | ``` markdown 174 | arithmetic/ 175 | : 176 | ├───tests/ 177 | | testAdd.m 178 | | testIntToWord.m 179 | └───toolbox/ 180 | add.m 181 | : 182 | ``` 183 | 184 | ### MATLAB Projects 185 | 186 | * [Projects](https://www.mathworks.com/help/matlab/projects.html) are a great way to ensure a consistent environment for your authoring team. It manages dependencies in complex projects, keeps the path correct, and integrates with source control systems. 187 | * Give the project file (with a `.prj` extension) the same name as the root folder. Put it in the root folder and check it into the source control system. 188 | 189 | If we look at our example toolbox: 190 | 191 | ```markdown 192 | arithmetic/ 193 | | README.md 194 | | arithmetic.prj 195 | | license.txt 196 | | toolboxPackaging.prj 197 | : 198 | └───resources/ 199 | ``` 200 | 201 | ### Source Control and `buildtool` (CI/CD Files) 202 | 203 | * Source control systems should be set up with this folder as the root of a source repository. Additional configuration files like `.gitatributes` and `.gitignore` belong in this folder. A `.gitignore` file for a typical MATLAB toolbox project can be found [here](https://github.com/mathworks/gitignore/blob/main/Global/MATLAB.gitignore). 204 | * Scripts related to packaging and shipping the toolbox should be placed in a `buildUtilities` folder under the root folder. Consider using the [`buildtool`](https://www.mathworks.com/help/matlab/matlab_prog/overview-of-matlab-build-tool.html) introduced in R2022b. The tasks functions associated with `buildtool` are in `buildfile.m`. 205 | 206 | ```markdown 207 | arithmetic/ 208 | │ .gitattributes 209 | │ .gitignore 210 | | README.md 211 | | arithmetic.prj 212 | | buildfile.m 213 | | license.txt 214 | | toolboxPackaging.prj 215 | ├───.git/ 216 | : 217 | ├───resources/ 218 | └───buildUtilities/ 219 | ``` 220 | 221 | ## Open in MATLAB Online and File Exchange badges for GitHub.com 222 | 223 | For your toolbox project hosted on GitHub.com, MathWorks offers 2 badges you can use: 224 | 225 | ![Open in MATLAB Online Badge](https://www.mathworks.com/images/responsive/global/open-in-matlab-online.svg) 226 | 227 | This opens your toolbox in MATLAB Online. This feature enables your users to try out your toolbox quickly. See [this page](https://www.mathworks.com/products/matlab-online/git.html) to learn more and create an Open in MATLAB Online badge. 228 | 229 | ![File Exchange Badge](https://www.mathworks.com/matlabcentral/images/matlab-file-exchange.svg) 230 | 231 | This provides an easy way for people visiting your GitHub repository to jump to your code on File Exchange. Once your File Exchange entry is set up, a tool will appear at the top of the page to assist you in creating a File Exchange badge. See [this posting](https://blogs.mathworks.com/community/2019/11/27/a-github-badge-for-the-file-exchange/) for more information. 232 | 233 | --- 234 | [![CC-BY-4.0](images/cc-by-40.png)](https://creativecommons.org/licenses/by/4.0/) 235 | 236 | Copyright © 2023, The MathWorks, Inc. 237 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | # Reporting Security Vulnerabilities 2 | 3 | If you believe you have discovered a security vulnerability, please report it to 4 | [security@mathworks.com](mailto:security@mathworks.com). Please see 5 | [MathWorks Vulnerability Disclosure Policy for Security Researchers](https://www.mathworks.com/company/aboutus/policies_statements/vulnerability-disclosure-policy.html) 6 | for additional information. 7 | -------------------------------------------------------------------------------- /images/PackagingTool.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mathworks/toolboxdesign/486ac15f8bb05dc0e29b6aa7a707aaa269457e5a/images/PackagingTool.jpg -------------------------------------------------------------------------------- /images/cc-by-40.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mathworks/toolboxdesign/486ac15f8bb05dc0e29b6aa7a707aaa269457e5a/images/cc-by-40.png --------------------------------------------------------------------------------