MATLAB Library System

MATLAB Library System is a lightweight modular packaging method addressing the inconvenient third party library handling in MATLAB. It provides a one-command way to install/uninstall the third party functionality into your MATLAB workspace permanently. It also defines a standard way for the library authors to add credit and versioning information and a quick start guide that can be used as a quick installation tester method.

MLS packages

A library distributed with the MATLAB Library System is wrapped around a top level folder. This folder wrapper is the MLS package. It contains the necessary install/uninstall scripts and the librarydata.txt file. The actual library containing the third party functionality is separated this way from the package handler logic.

my_mls_package
│   install.m
│   uninstall.m
│   librarydata.txt    
│
└───library
    │   files1.m
    │   files2.m
    │   ...
    │ 
    ├───folder1
    ├───folder2
    └───...

The installer script will add the library folder and all of it's subfolders into your MATLAB path permanently. The top level package folder (my_mls_package) won't be added, so your MATLAB workspace won't be polluted with the install and uninstall scipts. The library name for the folder inside the package is mandatory! Do not name it another way.

Installing an MLS package

After downloading and unzipping an MLS package the installation is straightforward.

1. Navigate into the top level MLS package folder in MATLAB
2. Run the install command
3. Done.

All the functions defined in the library folder and it's subfolders will be available in your MATLAB workspace. You can run the install command by typing in to the console, or by opening up the install.m script and running it manually.

Unistalling an MLS package

The method is similar to the installation steps.

1. Navigate into the top level MLS package folder in MATLAB
2. Run the uninstall command
3. Done.

All the functions defined in the library folder and it's subfolders will be removed from your MATLAB workspace.

Best practice

You can have a folder for your MLS packages somewhere in your machine where you can keep all of your third party modules and your own packages as well. You can create a install/uninstall all script that will install/uninstall all of your modules at once. In this way you can install all of your packages to your actual MATLAB workspace if you didn't do that already, or you are on a new machine.

Check out the latest release page. It will contain these scripts too. Make sure you only have MLS packages inside the folder you run the scripts, otherwise it wont work.

You can write your own scripts, that has a functionality something like this:

d = dir('.');
for k = 1:length(d)
    if (d(k).isdir == 1)
        switch d(k).name
            case '.'
            case '..'
                % Nothing to do
            otherwise
                cd(d(k).name)
                install()
                cd('..')
        end
    end
end

This code scans through the current directory, and calls the install command inside every folder it find in the first level.

Printout examples

By running the install script, an MLS package will print out the following.

>> install
 
#====================================================================================#
|                                                                                    |
|                      M A T L A B   L I B R A R Y   S Y S T E M                     |
|               >>-------------------------~-------------------------<<              |
|                                       v2.3.0                                       |
#------------------------------------------------------------------------------------#
 
   Installing My Library v0.0.0 by John Smith..
 
      -> Path added: .../my_mls_package/library
 
   Finished!
 
      My Library v0.0.0 has been succesfully installed to your system!
 
      Test your installation by running: my_function()
 
#====================================================================================#

By running the uninstall script, an MLS package will print out the following.

>> uninstall
 
#====================================================================================#
|                                                                                    |
|                      M A T L A B   L I B R A R Y   S Y S T E M                     |
|               >>-------------------------~-------------------------<<              |
|                                       v2.3.0                                       |
#------------------------------------------------------------------------------------#
 
   Removing My Library v0.0.0 by John Smith..
 
      -> Path removed: .../my_mls_package/library
 
   Finished!
 
      My Library v0.0.0 has been succesfully removed from your system!
 
#====================================================================================#

Creating your own MLS package

If you have written a library for MATLAB, and you want to ship it to others, you might want to create your own MLS package. This way your customers can install and manage your library with less effort.

1. Download the latest MLS package template

You can download the latest MLS package template added to the latest MATLAB Library System release. After unpacking the zip package, you can rename the top MLS package folder from my_mls_package to anything yout want.

You can also download the template with git by running the following command: git clone git@github.com:tiborsimon/matlab-library-system.git my_mls_package where my_mls_package will be the name of your top level MLS package folder.

2. Edit the librarydata.txt file

The librarydata.txt file is a simple text file containing the library related credit, verioning and demo informations line by line in a strict order. You have to follow the data orders as defined in the template:

My Library
http://google.com
John Smith
v0.0.0
my_function()

1st line: library name
2nd line: library url
3st line: author name
4th line: library version
5th line: demo command

The library name will be displayed as an URL to the library url as you could see in the previous section's printouts. The demo command will be displayed as an URL too, but itt will call the demo command on click. In this way it needs no effort by the user to try the just-installed new functionality.

3. Put your own library into the library folder

Make sure you put your library into the library folder. Do not rename the library folder otherwise the install and uninstall scripts won't work properly.

4. Done

You have created your MLS package that is ready to ship!

License

This project is under the MIT license. See the included license file for further details.

Copyright (c) 2015 Tibor Simon

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.