Setting up a Workspace

3.2 Setting up a Workspace

Note: The workspace makefiles require GNU make (a.k.a. gmake), version 3.77 or later, which is available from ftp://ftp.gnu.org/gnu/make. In the following text, when you're asked to run gmake, this refers to running the GNU make binary, which may be called gmake or make, depending on your installation.

A workspace is a directory which contains all necessary user-specific files needed to run Simics and develop modules. Setting up a workspace is done using the workspace-setup scripts, like this:

$ [simics]/bin/workspace-setup.bat $HOME/my-simics-workspace

where [simics] is the location of the Simics-installation. The script can also be invoked in a cmd.exe command prompt window. The .bat extension is necessary if the script is invoked in a Cygwin shell; Cygwin does not automatically append .bat as cmd.exe does.

Note: The workspace setup script does not rely on the configure being run in the installed Simics.

The script will create a workspace directory with the following contents:

`simics`	`simics-eclipse`	`GNUmakefile`
`compiler.mk`	`config.mk`	`.workspace-properties`
`modules/`	`targets/`	host`/`

simics: Starts Simics in command-line mode.
simics-eclipse: Starts Simics with the Eclipse frontend.
GNUmakefile: Makefile to build all modules under the modules directory. The file is called GNUmakefile to signify that it requires GNU make. Do not edit this file, instead you may create a file called config-user.mk, where you can override settings in config.mk.
compiler.mk: Make file that selects the C compiler to use by setting the CC variable. A matching C++ compiler will be searched for by config.mk in the same path as CC if CXX is not set. The compiler.mk file will not be overwritten when the workspace is updated.
config.mk: Includes [simics]/config/config.mk that contains default definition of make flags for different compilers, such as CFLAGS. Do not edit this file; override variables in config-user.mk instead.
config-user.mk: Optional file that may contain user defined make variables overriding the ones in [simics]/config/config.mk.
module-user.mk: Optional file that may contain user defined make targets and variables overriding the ones in [simics]/config/module.mk.
modules/: Contains user-developed modules. The default target in GNUmakefile builds all modules in the modules directory.
targets/: Contains some pre-configured machines, to be used as examples.
<host>/: The build working directory, which is named after the host type, for example x86-linux, v9-sol8-64, amd64-linux or x86-win32. When a module is compiled, any intermediate build files, like dependency and object files (.d .o) are generated in the <host>/obj/modules/<module>/ directory. The resulting module file is placed in <host>/lib/, and the Python command file for the module is copied to the <host/lib/python/ directory.
.workspace-properties: For internal use.

When the workspace has been created, you may type make (or possibly gmake) to build all the modules, or ./simics to start Simics.

In order to rebuild all modules, type make clean, followed by make. In order to rebuild just a single module, type make clean-<modulename>, for example:

$ make # builds all modules
$ make clean-mymodule # removes all objectfiles for "mymodule"
$ make mymodule # builds "mymodule"

The clean targets only remove object files and similar intermediates for the module not needed when running. To remove the actual module files as well, use make clobber or make clobber<modulename>.

3.2.1 Workspace setup script invocation

The workspace setup script is used to create and upgrade workspaces. It can also create module skeletons to start with when writing new devices.

The setup script is located in the bin subdirectory of the Simics installation, and is invoked like this:

$ [simics]/bin/workspace-setup [options] [workspace]

You may put the [simics]/bin directory in your PATH variable, and invoke the script directly.

$ workspace-setup [options] [workspace]

Option summary (can also be shown using the --help option):

-v, --version: Prints information about Simics (version, installation directory).
-n, --dry-run: Execute normally, but do change or create any files.
-q, --quiet: Do not print any info about the actions taken by the script.
--force: Force using a non-empty directory as workspace. Note: even with this option, modules in the module sub-directory will not be overwritten.
--device=MODULE_NAME: Generate skeleton code for a device, suitable to use as a starting point for implementing your own device. The default implementation language is DML. See the --c-device and --py-device options for creating devices using other languages. If the device already exists, this option is ignored. To recreate the skeleton, remove the device directory.
--c-device=MODULE_NAME: Similar to --device, but creates a device using C instead of DML.
--py-device=MODULE_NAME: Similar to --device, but creates a device using Python instead of DML.
--copy-device=MODULE_NAME: Copies the source for a sample device/module into the workspace. The files will be copied from the Simics installation. If the device already exist in your workspace, you must manually delete it first.

3.2.2 Updating workspaces

To upgrade your workspace to a new Simics version, run the script again with no arguments.

$ cd $HOME/my-simics-workspace
$ [path-to-new-simics]/bin/workspace-setup

It will do the necessary updates in the workspace, but leave the user-modifiable files intact. (Modified files that need to be overwritten are saved in backup versions with the extension ".~N~" (Unix) or "~N~.backup" (Windows), where N is the first free number.)

Previous - Up - Next