matlab.buildtool.tasks.PcodeTask Class

Namespace: matlab.buildtool.tasks
Superclasses: matlab.buildtool.Task

Task for creating P-code files

Since R2024a

Description

The matlab.buildtool.tasks.PcodeTask class provides a task for creating P-code files by obfuscating MATLAB^® source code. To obfuscate the code in .m files, the task calls the pcode function.

Tasks that you create with the PcodeTask class support incremental builds. For more information, see Up-To-Date Check.

Creation

Description

task = matlab.buildtool.tasks.PcodeTask(source,outputFolder) creates a task for obfuscating source code, and sets the Source and OutputFolder properties. The task obfuscates the .m files represented by source and saves the resulting P-code files to the specified output folder.

task = matlab.buildtool.tasks.PcodeTask(source,outputFolder,Name=Value) sets the Algorithm and PreserveSourceFolder properties using one or more name-value arguments. You can also set the Description and Dependencies properties, which the class inherits from the Task class, using name-value arguments. For example, task = matlab.buildtool.tasks.PcodeTask("src","out",PreserveSourceFolder=true) creates a task for obfuscating the contents of the src folder and saving the P-code files to the out/src folder.

Properties

This section lists the properties of the PcodeTask class. In addition to these properties, the PcodeTask class inherits properties from the Task class. Of the inherited properties, you can set the Description and Dependencies properties using name-value arguments during task creation.

Source — Source code to obfuscate

string vector | character vector | cell vector of character vectors | matlab.buildtool.io.FileCollection vector

Source code to obfuscate, specified as a string vector, character vector, cell vector of character vectors, or matlab.buildtool.io.FileCollection vector, and returned as a matlab.buildtool.io.FileCollection row vector. For example, you can specify a .m file, a folder that contains .m files, or a combination of files and folders. The task obfuscates all the .m files represented by Source.

Example: "src" represents all the source code in the src folder, including its subfolders.

Example: "src/*.m" represents all the .m files directly under the src folder.

Example: "src/**/*.m" represents all the .m files in the src folder and any of its subfolders.

Attributes:

GetAccess	public
SetAccess	public

OutputFolder — Output folder for P-code files

string scalar | character vector | matlab.buildtool.io.File object

Output folder for the P-code files, specified as a string scalar, character vector, or matlab.buildtool.io.File object, and returned as a matlab.buildtool.io.File object. If the folder does not exist, the task creates it.

The way the task saves P-code files to the output folder depends on the specified source code:

• If you specify a source file, the task saves its corresponding P-code file directly under the output folder. For example, if you specify "src/**/*.m", the task obfuscates all the files that match the specified pattern and saves the P-code files directly under the output folder.

• If you specify a source folder, the task obfuscates the contents of the folder and saves the P-code files using the original folder structure directly under the output folder.

Attributes:

GetAccess	public
SetAccess	public

Algorithm — Obfuscation algorithm

"R2022a" (default) | "R2007b"

Obfuscation algorithm used by the pcode function to create P-code files, specified as "R2022a" or "R2007b". By default, the task uses the enhanced "R2022a" algorithm.

Attributes:

GetAccess	public
SetAccess	public

Data Types: string | char

PreserveSourceFolder — Option to include source folders in output structure

false or 0 (default) | true or 1

Option to include the source folders specified when creating the task in the output folder structure, specified as a numeric or logical 0 (false) or 1 (true). If the value is true, the task includes the specified source folders in addition to their obfuscated contents in the output folder structure directly under OutputFolder. (For an example, see Include Source Folder in Output Folder Structure.) By default, the task includes only the obfuscated contents of the specified source folders in the output folder structure.

Note

The PreserveSourceFolder property affects only source folders and does not have an impact on how the task treats specified source files. For example, the name-value argument in task = matlab.buildtool.tasks.PcodeTask(["src1" "src2/*.m"],"out",PreserveSourceFolder=true) affects only how the task treats "src1", which specifies a folder. The name-value argument does not affect "src2/*.m", which specifies files.

Attributes:

GetAccess	public
SetAccess	public

PcodeFiles — P-code files to create

matlab.buildtool.io.FileCollection row vector

P-code files to create, returned as a matlab.buildtool.io.FileCollection row vector. You can use this property to programmatically access the P-code files. For example, you can return the paths to the P-code files by using p = plan("pcode").PcodeFiles.paths'. You can also specify the P-code files as inputs of other tasks, for instance, plan("archive").Inputs = plan("pcode").PcodeFiles.

Attributes:

GetAccess	public
SetAccess	private

Examples

Create P-Code Files from Source Folder

Create P-code files from the contents of a folder by using the PcodeTask class.

Open the example and then navigate to the pcode_task_example folder, which contains a build file.

cd pcode_task_example

Create the source files and folders used in this example. See the code of the local function createFile, which is used to create the files, at the end of this example.

mkdir source
createFile(fullfile("source","file1.m"))
createFile(fullfile("source","file2.m"))
mkdir source private
createFile(fullfile("source","private","file3.m"))
createFile(fullfile("source","private","file4.m"))

This code shows the contents of the build file. The build file contains one task that obfuscates the contents of the source folder and saves the P-code files to the output folder.

function plan = buildfile
import matlab.buildtool.tasks.PcodeTask

% Create a plan with no tasks
plan = buildplan;

% Add a task to create P-code files
plan("pcode") = PcodeTask("source","output");
end

Run the "pcode" task. The task obfuscates the contents of the source folder.

buildtool pcode

** Starting pcode
** Finished pcode

Return the paths of the P-code files by accessing the PcodeFiles property of the "pcode" task. The P-code files appear directly under the output folder using the original file structure.

plan = buildfile;
p = plan("pcode").PcodeFiles.paths'

p = 4×1 string
    "output\file1.p"
    "output\file2.p"
    "output\private\file3.p"
    "output\private\file4.p"

Local Function

This code shows the local function used in this example.

function createFile(filename)
fclose(fopen(filename,"w"));
end

Include Source Folder in Output Folder Structure

Include the source folder in addition to its obfuscated contents in the output folder structure created with the PcodeTask class.

Open the example and then navigate to the pcode_task_example1 folder, which contains a build file.

cd pcode_task_example1

Create the source files and folders used in this example. See the code of the local function createFile, which is used to create the files, at the end of this example.

mkdir source
createFile(fullfile("source","file1.m"))
createFile(fullfile("source","file2.m"))
mkdir source private
createFile(fullfile("source","private","file3.m"))
createFile(fullfile("source","private","file4.m"))

This code shows the contents of the build file. The build file contains one task that obfuscates the contents of the source folder. Because PreserveSourceFolder is specified as true, the task saves the P-code files to the output/source folder. In other words, it includes source in the output folder structure.

function plan = buildfile
import matlab.buildtool.tasks.PcodeTask
 
% Create a plan with no tasks
plan = buildplan;
 
% Add a task to create P-code files
plan("pcode") = PcodeTask("source","output",PreserveSourceFolder=true);
end

Run the "pcode" task. The task obfuscates the contents of the source folder.

buildtool pcode

** Starting pcode
** Finished pcode

Return the paths of the P-code files by accessing the PcodeFiles property of the "pcode" task. The P-code files appear in the output/source folder. If PreserveSourceFolder were false, the task would not include source in the output folder structure.

plan = buildfile;
p = plan("pcode").PcodeFiles.paths'

p = 4×1 string
    "output\source\file1.p"
    "output\source\file2.p"
    "output\source\private\file3.p"
    "output\source\private\file4.p"

Local Function

This code shows the local function used in this example.

function createFile(filename)
fclose(fopen(filename,"w"));
end

Create P-Code Files in Place

Create P-code files in the same folders as the source files by using the PcodeTask class.

Open the example and then navigate to the pcode_task_example2 folder, which contains a build file.

cd pcode_task_example2

Create the source files and folders used in this example. See the code of the local function createFile, which is used to create the files, at the end of this example.

mkdir source
createFile(fullfile("source","file1.m"))
createFile(fullfile("source","file2.m"))
mkdir source private
createFile(fullfile("source","private","file3.m"))
createFile(fullfile("source","private","file4.m"))

This code shows the contents of the build file. The build file contains one task that obfuscates the contents of the source folder and saves the P-code files to the same folders as the .m files.

function plan = buildfile
import matlab.buildtool.tasks.PcodeTask

% Create a plan with no tasks
plan = buildplan;

% Add a task to create P-code files
plan("pcode") = PcodeTask("source","source");
end

Run the "pcode" task. The task obfuscates the contents of the source folder.

buildtool pcode

** Starting pcode
** Finished pcode

Return the paths of the P-code files by accessing the PcodeFiles property of the "pcode" task. The P-code files appear in the same folders as the .m files.

plan = buildfile;
p = plan("pcode").PcodeFiles.paths'

p = 4×1 string
    "source\file1.p"
    "source\file2.p"
    "source\private\file3.p"
    "source\private\file4.p"

Local Function

This code shows the local function used in this example.

function createFile(filename)
fclose(fopen(filename,"w"));
end

Create P-Code Files from Pattern That Matches Source Files

Create P-code files from a Glob pattern that matches multiple files on disk by using the PcodeTask class. When you create a PcodeTask instance with specified source files, the task saves the corresponding P-code files directly under the specified output folder and does not observe the input folder structure.

Open the example and then navigate to the pcode_task_example3 folder, which contains a build file.

cd pcode_task_example3

Create the source files and folders used in this example. See the code of the local function createFile, which is used to create the files, at the end of this example.

mkdir source
createFile(fullfile("source","file1.m"))
createFile(fullfile("source","file2.m"))
mkdir source private
createFile(fullfile("source","private","file3.m"))
createFile(fullfile("source","private","file4.m"))

This code shows the contents of the build file. The build file contains one task that obfuscates the contents of the .m files in the source folder and any of its subfolders and saves all the P-code files directly under the output folder.

function plan = buildfile
import matlab.buildtool.tasks.PcodeTask

% Create a plan with no tasks
plan = buildplan;

% Add a task to create P-code files
plan("pcode") = PcodeTask("source/**/*.m","output");
end

Run the "pcode" task. The task obfuscates the contents of the source files.

buildtool pcode

** Starting pcode
** Finished pcode

Return the paths of the P-code files by accessing the PcodeFiles property of the "pcode" task. The P-code files appear directly under the output folder. The task did not observe the input folder structure because it was created with specified source files, not source folders.

plan = buildfile;
p = plan("pcode").PcodeFiles.paths'

p = 4×1 string
    "output\file1.p"
    "output\file2.p"
    "output\file3.p"
    "output\file4.p"

Local Function

This code shows the local function used in this example.

function createFile(filename)
fclose(fopen(filename,"w"));
end

More About

Up-To-Date Check

To avoid redundant work, the build tool does not run a PcodeTask instance if it is up to date and its DisableIncremental property is false. The build tool runs the task if the source code, P-code files, or obfuscation algorithm have changed since the last run:

• Source code — If you modify the source code or change the value of the Source property, the build tool runs the task.

• P-code files — If you modify or remove any of the existing P-code files or change the value of the OutputFolder or PreserveSourceFolder property, the build tool runs the task.

• Obfuscation algorithm — If you change the value of the Algorithm property, the build tool runs the task.

Tips

• You cannot overwrite or remove the actions of a built-in task, but you can specify additional task actions. For example, append an action to the Actions property of a built-in task.

  plan("myTask").Actions(end+1) = @myAction;

Version History

Introduced in R2024a