sscbuild

Build custom library from collection of Simscape files

Since R2024b

Syntax

sscbuild(namespace)

sscbuild(namespace,'-output',outputlibrary)

sscbuild namespace

sscbuild

Description

sscbuild(namespace) generates a custom Simscape™ library file from the specified namespace, namespace. Call sscbuild from the namespace parent folder, that is, from the folder containing the top-level namespace folder. For more information on namespace folder structure, see Organizing Your Simscape Files.

When you call sscbuild with one argument, the library file is named namespace_lib and is located in the namespace parent folder. The library contains all the sublibraries and blocks generated from the Simscape files (either source or protected) located in the namespace and its subfolders. Simscape protected files have higher precedence than the source files when you build a library. If both the protected and the source files are present in the namespace and the source files are newer than the protected files, sscbuild uses the protected files to build the library, but issues a warning.

sscbuild(namespace,'-output',outputlibrary) generates a custom Simscape library file from the specified namespace, namespace, with outputlibrary defining the library file name and location. This syntax uses a name-value argument pair, where '-output' is the name of the optional argument and outputlibrary is the argument value. The function implements partial argument name matching, therefore specifying '-o' as the argument name also works.

sscbuild namespace is the command form of the syntax. Command form requires fewer special characters. You do not need to type parentheses or enclose the input in single or double quotes. Separate inputs with spaces instead of commas.

For example, to build a namespace named +MyNamespace, these statements are equivalent:

sscbuild MyNamespace        % command form
sscbuild('MyNamespace')     % function form

You can also use command form with the name-value argument pair, described in the previous syntax, as long as the path and name of the output library is a character vector. For example, to build a namespace named +MyNamespace and save the output library as 'C:\Work\MyLibrary', these statements are equivalent:

sscbuild MyNamespace -output C:\Work\MyLibrary          % command form
sscbuild('MyNamespace','-output','C:\Work\MyLibrary')   % function form

Do not use command form when outputlibrary uses variables, or functions like fullfile, to specify the output library name and location. For more information on the command-function duality, see Choose Command Syntax or Function Syntax.

sscbuild is a special syntax, with no arguments, that you can use to call the function from inside the namespace folder structure. It builds a library from the current namespace, with default library name and location. To specify a different name or location for the output library, call sscbuild from the namespace parent folder using either the command or the function form of the syntax with the name-value argument pair.

Examples

Build Custom Block Library with Default Name

Suppose your top-level namespace folder, where you store your Simscape files, is named +SimscapeCustomBlocks and is located in C:\Work\MyLibraries.

To generate a custom block library, change your current working folder to C:\Work\MyLibraries. Then, at the MATLAB^® Command prompt, type:

sscbuild('SimscapeCustomBlocks');

You can also use the command form of this syntax, which requires fewer special characters:

sscbuild SimscapeCustomBlocks;

This command generates a Simulink^® model file called SimscapeCustomBlocks_lib in the namespace parent folder, C:\Work\MyLibraries (that is, in the same folder that contains your +SimscapeCustomBlocks namespace).

Specify Name and Location when Building Custom Block Library

Suppose your top-level namespace folder, where you store your Simscape files, is named +CustomElectricalBlocks and is located in C:\Work. You want to generate a custom block library from this namespace, place it in C:\Work\MyLibraries, and give it a shorter and more meaningful name, CustomDiodes. You do this by providing the name-value argument pair to the sscbuild function.

To generate the custom block library, change your current working folder to C:\Work. Then, at the MATLAB Command prompt, type:

sscbuild('CustomElectricalBlocks','-output','C:\Work\MyLibraries\CustomDiodes')

Generating Simulink library 'CustomDiodes' in the output directory 'C:\Work\MyLibraries' ...

This function call generates a Simulink model file called CustomDiodes.slx in the specified folder. Add the C:\Work\MyLibraries folder to the MATLAB path to facilitate using these custom blocks in various models.

Build Custom Block Library from Read-Only Source Files

Suppose your namespace with source files is located in a read-only folder. For example, the +BatteryPack namespace is used in the Lithium-Ion Battery Pack with Fault Using Arrays example. For more information on this namespace, see Case Study — Battery Pack with Fault Using Arrays.

To generate a custom block library from the +BatteryPack namespace, you must specify a location for the output library other than the read-only parent folder of the namespace. You do this by providing the name-value argument pair to the sscbuild function. In this example, the output folder name is a character vector, which allows you to use the command form of the syntax.

Change your current working folder to the folder containing the +BatteryPack namespace.

cd(matlabroot)
cd toolbox/physmod/simscape/supporting_files/example_libraries 

At the MATLAB Command prompt, type:

sscbuild BatteryPack -output C:\Work\BatteryPack_lib

Generating Simulink library 'BatteryPack_lib' in the output directory 'C:\Work' ...

This command generates a Simulink model file called BatteryPack_lib in the specified output folder, C:\Work.

You can also take advantage of the partial argument name matching and shorten the command syntax even more:

sscbuild BatteryPack -o C:\Work\BatteryPack_lib

This command is equivalent to the previous one.

Input Arguments

namespace — Name of namespace containing Simscape files

character vector | string scalar

Name of namespace containing Simscape files, specified as a character vector or a string scalar and located in the folder from which you call the sscbuild function. namespace is the name of the top-level namespace folder without the leading + character. When you call sscbuild using the command syntax, do not use quotes around namespace. For more information on the command-function duality, see Choose Command Syntax or Function Syntax.

Example: sscbuild MyNamespace is the command syntax to build a library from the namespace +MyNamespace. The equivalent function syntax is sscbuild('MyNamespace').

outputlibrary — Full path and name of generated block library file

character vector | string scalar

Name and location of the block library file generated from the namespace, specified as a character vector or a string scalar. When you call sscbuild using the function syntax, you can also use MATLAB variables and functions, such as fullfile or genpath, to specify the path to the library file.

If you specify a file name without the path, the library is generated in your current working folder. When you specify the file name, you can include the file extension, .slx, or omit it.

Example: fullfile(tempdir,'MyLibrary.slx') with function syntax, you can use MATLAB variables and functions to specify the path.

Version History

Introduced in R2024b