test-framework-extensions/buildfile.m at main · mathworks/test-framework-extensions · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
function plan = buildfile()
%buildfile Test Framework Extensions buildfile

% Copyright 2026 The MathWorks, Inc.

import matlab.buildtool.*
import matlab.buildtool.tasks.*

plan = buildplan;

% Folders of interest
prj = plan.RootFolder;
tbx = fullfile( prj, "tbx" );
api = fullfile( tbx, tbxname() );
doc = fullfile( tbx, tbxname() + "doc" );
test = fullfile( prj, "tests" );

% Clean task
plan("clean") = CleanTask;

% Check task group
plan("check:code") = CodeIssuesTask( prj, ...
    Configuration="factory", ...
    IncludeSubfolders=true, ...
    WarningThreshold=0 );

plan("check:project") = Task( ...
    Description="Run MATLAB project checks", ...
    Actions=@checkProject, ...
    Inputs=api );

% Test task
plan("test") = TestTask( test, ...
    SourceFiles=tbx, ...
    Strict=true, ...
    Dependencies="check" );

% Documentation task
plan("doc") = Task( ...
    Description="Generate documentation", ...
    Actions=@buildDoc, ...
    Inputs=doc, ...
    Outputs=[ ...
        fullfile( doc, "**", "*.html" ), fullfile( doc, "*.xml" ), ...
        fullfile( doc, "resources" ), fullfile( doc, "helpsearch-v*" )] );

% Package task
plan("package") = Task( ...
    Description="Package toolbox", ...
    Actions=@packageToolbox, ...
    Inputs=tbx, ...
    Outputs="releases/*.mltbx", ...
    Dependencies=["test" "doc"] );

% Default task
plan.DefaultTasks = "package";

end % buildfile

function n = tbxname()
%tbxname  Toolbox name

n = "testext";

end % tbxname

function checkProject(~)
% Run MATLAB project checks

p = currentProject();
p.updateDependencies();
t = table( p.runChecks() );
ok = t.Passed;
if any( ~ok )
    disp( t(~ok,:) )
    error( "build:check", "Project check(s) failed." )
else
    fprintf( 1, "** Project checks passed\n" )
end

end % checkProject

function buildDoc(context)
% Generate documentation

% Documentation folder
doc = context.Task.Inputs.paths;

% Convert Markdown to HTML
md = fullfile( doc, "**", "*.md" );
html = docconvert( md, Theme="light" );
fprintf( 1, "** Converted Markdown doc to HTML\n" )

% Run code and insert output
docrun( html, Theme="light", FigureSize=[600 400] )
fprintf( 1, "** Inserted MATLAB output into doc\n" )

% Index documentation
docindex( doc )
fprintf( 1, "** Indexed doc\n" )

end % buildDoc

function packageToolbox(context)
% Package toolbox

n = tbxname();

% Load and tweak metadata
s = jsondecode( fileread( n + ".json" ) );
v = ver( n ); % from Contents.m
assert( isscalar( v ), "build:package", ...
    "Found %d instances of %s on the MATLAB path.", numel( v ), n )
s.ToolboxName = v.Name;
s.ToolboxVersion = v.Version;

if getenv( "GITHUB_ACTIONS" ) == "true"
    % Check version and tag compatibility for release
    ref = string( getenv( "GITHUB_REF" ) );
    gitTagNumber = extractAfter( ref, "refs/tags/v" );
    assert( v.Version == gitTagNumber, ...
        "build:package:VersionTagMismatch", ...
        "%s Toolbox version %s (from Contents.m) does not " + ...
        "match the current Git tag number (%s).", ...
        v.Name, v.Version, gitTagNumber )
    % Define stable name for GitHub
    stableName = erase( v.Name, " " ) + ".mltbx";
    s.OutputFile = fullfile( "releases", stableName );
else
    % Include version in toolbox file name
    s.OutputFile = fullfile( ...
        "releases", v.Name + " " + v.Version + ".mltbx" );
end % if

% Create options object
f = s.ToolboxFolder; % mandatory
id = s.Identifier; % mandatory
s = rmfield( s, ["Identifier", "ToolboxFolder"] ); % mandatory
pv = [fieldnames( s ), struct2cell( s )]'; % optional
o = matlab.addons.toolbox.ToolboxOptions( f, id, pv{:} );
o.ToolboxVersion = string( o.ToolboxVersion ); % g3079185

% Remove markdown
md = endsWith( o.ToolboxFiles, ".md" );
o.ToolboxFiles(md) = [];

% Package
matlab.addons.toolbox.packageToolbox( o )
fprintf( 1, "[+] %s\n", o.OutputFile );

% Add license
lic = fileread( fullfile( context.Plan.RootFolder, "LICENSE.txt" ) );
mlAddonSetLicense( char( o.OutputFile ), struct( "type", 'BSD', "text", lic ) );

end % packageToolbox