As toolboxes (and their modules) are always in constant development and therefore even important details of the code might change from time to time, it is very important to have some sort of versioning scheme. The same is true for the modules written for the toolbox, and both, the versions of the toolbox and the modules are normally not synchronised.

The toolbox itself provides a version number that gets added to every history record written for a dataset, and as modules might well have versions independent from the main toolbox, it is equally important to implement a version numbering scheme and add that version number to each history record of tasks performed with the module, such as to allow the user to always track which version was used for a particular task.

In combination with a source code management system (such as git) this allows for identifying the exact code used for that particular task in retrospect.

Thankfully, Matlab™ provides its users with a rather convenient way of performing this task, in terms of the Contents.m file that is placed normally within the root folder of whatever toolbox or module. Following is an example of such a file:

Contents.m

% trEPR Toolbox <YourModuleName> module
% Version 0.1.1 07-Jun-2012

This file is the one and only place to store and maintain the version number and date of your toolbox module. Just to say it again: Under no circumstances ever try to store the version number (and date) of your toolbox module in any other place.

Please have a look at the scheme of version numbers of the toolbox and stick to that scheme whereever possible with your module version numbers as well.

Everytime you need to access the version number of your module from within Matlab™, use a special function dedicated to the task of exactly providing you with this and a bunch of additional information.

One example for such a routine is shown in the following code listing. Beware that the naming convention of this routine should generally be “trEPR<YourModuleName>info.m”, and it should be placed in the directory “internal” inside your module directory. For details, refer to the directory layout of your module section.

trEPRSIMinfo.m

function varargout = trEPRSIMinfo(varargin)
% TREPRSIMINFO Display/return information about the trEPR toolbox SIM
% module.
%   TREPRSIMINFO without any input and output parameters displays
%   information about the trEPR toolbox SIM module.
%
%   If called with an output parameter, TREPRSIMINFO returns a structure
%   "info" that contains all the information known to Matlab(r) about the
%   trEPR toolbox SIM module.
%
% Usage
%   trEPRSIMinfo
%
%   info = trEPRSIMinfo;
%
%   version = trEPRSIMinfo('version')
%   url = trEPRSIMinfo('url')
%   dir = trEPRSIMinfo('dir')
%
%   info    - struct
%             Fields: maintainer, url, bugtracker, vcs, version, path,
%                     name, description
%
%             maintainer  - struct
%                           Fields: name, email
%
%             url         - string
%                           URL of the toolbox website
%
%             bugtracker  - struct
%                           Fields: type, url
%
%             vcs         - struct
%                           Fields: type, url
%
%             version     - struct
%                           Fields: Name, Version, Release, Date
%                           This struct is identical to the output of the
%                           Matlab(r) "ver" command.
%
%             path        - string
%                           installation directory of the toolbox
%
%             name        - string
%                           name of the toolbox module
%
%             description - string
%                           short description of the toolbox module
%
%   version - string
%             <version> yyyy-mm-dd
%
%   url     - string
%             URL of the toolbox website
%
%   dir     - string
%             installation directory of the toolbox
%
% See also VER
 
% (c) 2012, Till Biskup
% 2012-06-07
 
% The place to centrally manage the revision number and date is the file
% "Contents.m" in the root directory of the trEPR toolbox SIM module.
%
% THE VALUES IN THAT FILE SHOULD ONLY BE CHANGED BY THE OFFICIAL MAINTAINER
% OF THE TOOLBOX MODULE!
%
% As the "ver" command works not reliably, as it works only in case the
% toolbox module is on the Matlab(r) search path, we parse this file here
% manually.
%
% Additional information about the maintainer, the URL, etcetera, are
% stored below. Again:
%
% THESE VALUES SHOULD ONLY BE CHANGED BY THE OFFICIAL MAINTAINER OF THE
% TOOLBOX MODULE!
 
info = struct();
info.maintainer = struct(...
    'name','<your name>',...
    'email','<your email address>'...
    );
info.url = '';
info.bugtracker = struct(...
    'type','BugZilla',...
    'url',''...
    );
info.vcs = struct(...
    'type','git',...
    'url',''...
    );
info.description = ...
    'a module for the trEPR toolbox for simulating trEPR spectra';
 
% For all version information, parse the "Contents.m" file in the toolbox
% root directory
% Get path to file "Contents.m"
[path,~,~] = fileparts(mfilename('fullpath'));
contentsFile = [ path(1:end-8) 'Contents.m' ];
% Read first two lines of "Contents.m"
contentsFileHeader = cell(2,1);
fid = fopen(contentsFile);
k=1;
for k=1:2
    contentsFileHeader{k} = fgetl(fid);
end
fclose(fid);
 
info.name = contentsFileHeader{1}(3:end);
C = textscan(contentsFileHeader{2}(3:end),'%s %s %s %s');
 
info.version = struct();
info.version.Name = contentsFileHeader{1}(3:end);
info.version.Version = C{2}{1};
if isempty(C{4})
    info.version.Release = '';
    info.version.Date = ...
        datestr(datenum(char(C{3}{1}), 'dd-mmm-yyyy'), 'yyyy-mm-dd');
else
    info.version.Release = C{3}{1};
    info.version.Date = ...
        datestr(datenum(char(C{4}{1}), 'dd-mmm-yyyy'), 'yyyy-mm-dd');
end
 
% Get install directory
[path,~,~] = fileparts(mfilename('fullpath'));
info.path = path(1:end-9);
 
if nargin
    switch lower(varargin{1})
        case 'version'
            varargout{1} = ...
                sprintf('%s %s',info.version.Version,info.version.Date);
        case 'url'
            varargout{1} = info.url;
        case 'dir'
            varargout{1} = info.path;
        otherwise
    end
elseif nargout
    varargout{1} = info;
else
    fprintf('==========================================================================\n');
    fprintf('\n');
    fprintf(' %s\n',info.name);
    fprintf(' - %s  \n',info.description);
    fprintf('\n');
    fprintf(' Release:         %s %s\n',info.version.Version,info.version.Date);
    fprintf(' Directory:       %s\n',info.path);
    fprintf(' Matlab version:  %s\n',version);
    fprintf(' Platform:        %s\n',platform);
    fprintf('\n');
    fprintf(' Homepage:        %s\n',info.url);
    fprintf(' Maintainer:      %s, <%s>\n',info.maintainer.name,info.maintainer.email);
    fprintf('\n');
    fprintf(' Bug tracker:     %s\n',info.bugtracker.url);
    fprintf('\n');
    fprintf('==========================================================================\n');
end
 
end

In this routine, only the first part after the comment header is of interest, where you add all the necessary information to the info structure, according to your needs.

Probably the most important case in your code, getting the version number of the toolbox module, is performed by a line like that:

version = trEPR<YourModuleName>info('version')

This will return the version number that you can use, e.g., for adding to history records. All other possible uses of the trEPR<YourModuleName>info routine are layed out in the respective help.