For purposes of this example we assume that we are using the QSP-x86 platform, that the customer has extended it with a device named secondstep, and that the new platform is called thirdstep. Finally, we assume that the goal is to distribute a single .tar.gz file.
About installing Simics Base and QSP-x86, see Simics Installation Guide. In this example we will do the installation to folder ./install.
Set up a Simics project as well as create and compile a sample device.
:~/example$ ./install/simics-6.0.0/bin/project-setup project
Project created successfully
:~/example$ cd project/
:~/example/project$ ./bin/project-setup --device secondstep
Skeleton for module 'secondstep' successfully created.
:~/example/project$ make
=== Environment Check ===
'/home/joe/example/project' is up-to date
gcc version 10
=== Building module "secondstep" ===
module_id.c
DEP module_id.d
DML-DEP secondstep.dmldep
DMLC secondstep-dml.c
DEP secondstep-dml.d
DMLC secondstep-dml.c
PYC module_load.py
CC secondstep-dml.o
CC module_id.o
CCLD secondstep.so
:~/example/project$
Copy a target script from the installation of QSP-x86 to the targets folder, and edit it.
:~/example/project$ mkdir targets/thirdstep
:~/example/project$ cp targets/qsp-x86/qsp-clear-linux.simics targets/thirdstep/thirdstep.simics
:~/example/project$
From targets/thirdstep/thirdstep.simics file, remove any lines reading "# Auto-generated file. ...". Such lines will prevent the file from being included in the upcoming package. Optionally, update the decl block if it exists, or add such a block. Finally edit the parameter to run-command-file as shown.
decl {
params from "%simics%/targets/qsp-x86/qsp-clear-linux.simics"
default system_info = "Thirdstep - Linux"
default ip_address = "10.10.0.4"
}
run-command-file "%simics%/targets/qsp-x86/qsp-clear-linux.simics"
Create a Simics package based on the project.
:~/example/project$ ./bin/project-packager
Descriptive Name [Customer Package] ThirdStep Package with Second Step Device
Package Name (no spaces) [Customer-Package] thirdstep
Package Number [200000]
Version [6.0.0]
Host Type (linux64/win64) [linux64]
Build ID Namespace [customer]
Build ID [6123]
Edit Files? (y/n) [n]
:~/example/project$
A packageinfo/thirdstep-linux64.tar.gz file has been created. The package include the sample device based on secondstep, the target script, and some other files.
Install the new package and associate it with Simics Base.
:~/example/project$ cd ../install/
:~/example/install$ tar -xzf ../project/packageinfo/thirdstep-linux64.tar.gz
:~/example/install$ ./simics-6.0.0/bin/addon-manager -s simics-thirdstep-6.0.0/
Simics 6 Add-on Package Manager
=================================
This script will configure this Simics installation to use optional
Simics add-on packages.
Default alternatives are enclosed in square brackets ([ ]).
=== Using the package list in Simics installation (~/example/install/simics-6.0.0) ===
Configured add-on packages:
QSP-x86 6.0.0 ../simics-qsp-x86-6.0.0
The following operations will be performed:
-> Add thirdstep 6.0.0 ../simics-thirdstep-6.0.0
New package list:
QSP-x86 6.0.0 ../simics-qsp-x86-6.0.0
thirdstep 6.0.0 ../simics-thirdstep-6.0.0
Do you want to update the package list? (y/n) [y]
Package list updated
:~/example/install$
Create a Simics project and run the newly created package briefly.
:~/example$ cd ../
:~/example$ ./install/simics-6.0.0/bin/project-setup test-project
Project created successfully
:~/example$ cd test-project/
:~/example/test-project$ ./simics targets/thirdstep/thirdstep.simics -e quit
Simics 6 (build 6123 linux64) © 2022 Intel Corporation
Use of this software is subject to appropriate license.
Type 'copyright' for details on copyright and 'help' for on-line documentation.
:~/example/test-project$
Install Simics Base and QSP-x86 to a clean location. Copy needed files and install the newly created package as well as associate it with Simics Base. In this example, install to folder ../test-install.
:~/example/test-project$ cd ../example/simics-6-install/
:~/example/simics-6-install$ ./install-simics.pl
...
:~/example/simics-6-install$ cd ../test-install/
:~/example/test-install$ tar -xzf ../project/packageinfo/thirdstep-linux64.tar.gz
:~/example/test-install$ ./simics-6.0.0/bin/addon-manager -s simics-thirdstep-6.0.0/
...
:~/example/test-install$
Check that the .package-list lists only relative file paths. Otherwise, edit paths accordingly.
:~/example/test-install$ cat simics-6.0.0/.package-list
../simics-thirdstep-6.0.0
../simics-qsp-x86-6.0.0
:~/example/test-install$
Create a file archive including the newly created package, Simics Base and QSP-x86.
:~/example/test-install$ cd ../
:~/example$ tar -czf distribution.tar.gz test-install/
:~/example$
On Linux, the project-packager script can create an encrypted Simics package based on the files of the project, that can be installed directly with the Simics installer.
Run the project-packager script with the flag -e (--encrypt) and provide a key with 64 hexadecimal digits.
:~/example/project$ ./bin/project-packager -e
Descriptive Name [Customer Package] Encrypted Thirdstep package
Package Name (no spaces) [Customer-Package] Encrypted-ThirdStep
Package Number [200000] 200001
Version [6.0.0]
Host Type (linux64/win64) [linux64]
Build ID Namespace [customer]
Build ID [6123]
Edit Files? (y/n) [n]
Key [0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF]
:~/example/project$
Now the packageinfo directory will contain the non-encrypted tar-files, that could be added to the installation with the addon-manager script as previously described, and encrypted Simics packages.
Copy the files for the encrypted package into the simics-6-install folder, and install.
:~/example$ cd simics-6-install/
:~/example$ cp project/packageinfo/package-200001-6.0.0-linux64.* .
:~/example/simics-6-install$ ./install-simics.pl
...
Now it is possible to test the installed packages as in the earlier example.
The project-packager could be run with a number of additional parameters. For a complete documentation of these parameters as well as a description of the normal usage of the script, run it with the -h parameter (or using the verbatim version of the same parameter: --help):
:~/project$ ./bin/project-packager -h
Here is the description of some parameters:
The -n parameter (verbatim --dry-run) runs the script without producing and output files. This makes it possible to test what inputs the script needs without creating any real files.
The -d parameter (verbatim --debug) gives some additional debug information when running the script, for example on what directory the script is run in and what the default values and names of the results of the script are.
The -b parameter (verbatim --batch) lets the user run the script without any interactive input. The script will then be run with the same default values and names that will be printed running the script interactively.
The -s, -t and -z parameters (verbatim --suppress, --tar and --zip) handle what type of compression (if any) that should be used to create the user packages. On Linux, the default is to use "tar" and "gz" and create ".tar.gz" packages. For Windows, the default is to create ".zip" packages.