matlab.buildtool.tasks.PcodeTask Class

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

Task for creating P-code files

Since R2024a

expand all in page

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. The task obfuscates the .m files represented by source and saves the resulting P-code files to the specified output folder.

example

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.

example

Input Arguments

expand all

Source code to obfuscate, specified as a string vector, character vector, cell vector of character vectors, or matlab.buildtool.io.FileCollection 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.

This argument sets the Source property.

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.

Output folder for the P-code files, specified as a string scalar, character vector, or 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.

This argument sets the OutputFolder property.

Properties

expand all

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 code to obfuscate, specified as a string vector, character vector, cell vector of character vectors, or matlab.buildtool.io.FileCollection vector, and stored 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.

Attributes:

GetAccess
public
SetAccess
public

Output folder for the P-code files, specified as a string scalar, character vector, or matlab.buildtool.io.File object, and stored 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

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

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

P-code files to create, represented 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

collapse all

Open Live Script

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
Open Live Script

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
Open Live Script

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
Open Live Script

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

expand all

Tips

  • You cannot overwrite or remove the action 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

See Also

Functions

Topics