Updated: October 28, 2024 |
Generate a QNX Neutrino virtual machine image
mkqnximage --type=vmware|vbox|qemu [--build] [--clean] [--config=file[:file]...] [--defaults [=option]] [--extra-dirs=none|directory_list] [--getip] [--graphics [= yes | no ]] [--help [=option|brief]] [--hostname=hostname][--options] [--policy=none|path] [--repos=dir[:dir]...] [--run [= options | -h ]] [--stop] [--telnet [= yes | no ]] [--wipe]
Linux, Mac, Microsoft Windows
For additional options not described here, use --help and --options.
Force a rebuild of the system image.
Because mkqnximage sometimes uses files from previous builds instead of regenerating them (for efficiency), rebuilding with --clean can be a helpful troubleshooting step.
mkqnximage --config=set1:set2
This option waits for the system image to be up and running before it returns a value.
--help=brief — Display a brief description of all options.
You can use this option to specify a different name. For example:
mkqnximage --type=vmware --run --hostname=qnx
For example, use the following command to search both $QNX_TARGET and ~/qnx/stage for files to include:
mkqnximage --repos='$QNX_TARGET:~/qnx/stage'
The
following command also searches both $QNX_TARGET and
~/qnx/stage, but prefers files in
~/qnx/stage:
mkqnximage --repos='~/qnx/stage:$QNX_TARGET'
--run=-h — Run the system image in the current directory in headless mode. The system image runs in the background without displaying anything on the screen.
The mkqnximage utility is a QNX Neutrino virtual machine image generator. It can generate images to run in the following virtualization environments:
VirtualBox — A free and open-source hosted hypervisor for x86 virtualization.
QEMU (Quick EMUlator) — A free and open-source emulator.
You can configure various options for the generated images, including the target CPU architecture. Currently, only the following combinations of host OS, VM platform, and target CPU architecture are supported:
Virtualization Technology | Host OS | QNX Guest CPU Architecture |
---|---|---|
VMware | Windows | x86-64 |
VirtualBox | Windows | x86-64 |
VirtualBox | macOS | x86-64 |
QEMU | Ubuntu | x86-64 |
There is no limit to the number of QNX Neutrino images you can create, but each one has to be in a different directory.
For information on creating an image on real hardware, see the BSP documentation for your board.
If this is the first time using VirtualBox, make sure it has a network interface before you run mkqnximage. To create a network, select the Network settings from Tools from the left pane and then click on the Create icon. Also, you have to enable DHCP.
To use mkqnximage on Microsoft Windows from a cmd window, first locate and run the file qnxsdp-env.bat from the base directory of a QNX Software Center installation.
The mkqnximage utility supports more options than the ones listed above. To display the complete set of options with a brief description of each, run the following command:
mkqnximage --help=brief
For detailed information about a specific option, specify an option name instead of brief. Specify --help by itself to display all options with full descriptions.
Whenever you run mkqnximage, it operates on the image in the current directory, whether you are building or running an image or getting its IP address.
In most cases, when you create a new system image, you start with an empty directory.
When mkqnximage first builds an image, it creates the following directories:
The output/build directory contains the build files and startup scripts that mkqnximage generates. You can edit these files and scripts as a quick way to try things out and diagnose problems. However, be aware that the contents of the output/build directory is regenerated when you run mkqnximage with updated options.
Use --run to start the image in the current directory and --stop to stop it.
If you are using VMware Workstation Player, you cannot use mkqnximage to start and stop images. Instead, open the file local/vmware_files/vmware.vmx.
You can combine other options with --run. If the options are different than the ones you used to build the image, mkqnximage rebuilds the image before it runs it; otherwise, it just runs it. If needed, you can use --build to force a rebuild of the system image when you run it. For example, you can force a rebuild to pick up changed versions of files.
The --getip option outputs the IP address of the system image if it is currently running. You can then use ssh to log in. You can also use telnet if you specify --telnet.
You can use scp and sftp to transfer files to and from the virtual machine.
Images built by mkqnximage include the users root, qnxuser, and user1 to user6. The password for each user is the same as the username.
When you run mkqnximage, the options you specify are preserved in local/options. To make changes, run mkqnximage and specify just the options you want to change. Use --options to display the current set of preserved options.
Use the following command to revert a single option to its default value:
mkqnximage --defaults=option
To revert all options to their default values, specify --default on its own.
The filesystems on images built by mkqnximage are organized to achieve the best results for an embedded system rather than the traditional UNIX layout. No filesystem (other than possibly the IFS) is mounted at /. Instead, an image has the following filesystems:
When you no longer need the system image, use --wipe to unregister it from any virtualization environments where it is registered (if the environment allows it), and delete the local and output directories.
The mkqnximage utility cannot remove a virtual machine from VMware. The --wipe option frees all disk space used by the image, but the virtual machine in VMware’s Virtual Machine Library has to be deleted manually.
Both VMware and VirtualBox allow you to delete virtual machines including all associated files. While this action prevents the image from being run, because all the options are preserved, you can restore it by simply re-running mkqnximage.
You can add content to files generated by mkqnximage as well as add new files to the image, which allows you to, for example, start new services on boot.
To make these changes, you edit 'snippet' files in the local/snippets directory. The most commonly used files are created for you, and you can create more as needed.
Each snippet file name has a prefix that determines what it does and a suffix that makes its name unique. Although the suffix is usually .custom, you can use a different value. For example, to add files to the system partition, you edit the file local/snippets/system_files.custom, and to add files to the IFS, you edit local/snippets/ ifs_files.custom.
The format of a snippet file depends on the file. For a snippet file that adds files to the system, the format must be in mkifs buildfile format for the IFS or mkqnx6fsimg buildfile format for the other two filesystems. The mkqmximage utility recognizes the following snippet file prefixes:
File prefix | Description |
---|---|
ifs_files | Includes additional files in the IFS. Uses the mkifs buildfile format. |
system_files | Includes additional files in the system partition. Uses the mkqnx6fsimg buildfile format. |
data_files | Includes additional files in the data partition. Uses the mkqnx6fsimg buildfile format. |
ifs_env | Used mainly for creating procmgr symlinks and setting environment variables at the beginning of the IFS startup script. These files must use the format defined for script files by mkifs. |
ifs_start | Commands used for starting the system. These commands include security policy loading if appropriate and execution of the startup script or SLM depending on the method used for starting the system. These files must use the format defined for script files by mkifs. |
post_start | Included in post_startup.sh, a shell script run at the end of startup.sh and by the SLM configuration file. It should contain commands that ksh can handle. |
slm | Included in the SLM configuration file. |
profile | Included in target system's /system/etc/profile, which is the file run when a user logs in to set up their environment. It should contain commands that ksh can handle. |
passwd_file, shadow_file,group_file | Include content in the passwd, shadow and group files. The format of these files must match that used by /etc/passwd, /etc/shadow, and /etc/group. |
definitions | Insert into the start of all preprocessed files to define preprocessor symbols. |
options | Define special options. This file is formatted as one or more bash variable assignments. Setting the variable PROC_OPTIONS appends the value of this variable to the procnto command line options. |
To include your own files in an image, either provide full paths to the files or use --repos to specify the paths to search.
If you have sets of options that you use frequently, you can save their values in a file and apply them using --config. The files are treated as bash scripts that are sourced by mkqnximage and are expected to set one or more variables to indicate new values for options. For example, a file contains the following line:
OPT_SECURE_PROCFS='yes'
When you load the file using --config, the effect is the equivalent to specifying --secure-procfs=yes.
The current settings of all options in this format are in the file local/options. If you set the environment variable MKQNXIMAGE_CONFIG to a path to this type of file, mkqnximage uses the file to provide the initial configuration whenever it creates a new system image.
Because the configuration file is a bash script, it can do more than set variables. For example, it can set the --hostname option based on the name of the current directory.
If the --getip option fails to return an address, it most likely means that the virtual machine is not running or failed to boot. If have this issue when the machine is running, you should check the console for indications of an error.
If a system fails to boot, check first that you've chosen a virtualization environment that is available on your system. The mkqnximage utility reports the target type after it builds the image.
In some cases, the source of problems might be that some files are not generated as they should be after one or more local changes or QNX packages are updated. To ensure this is not the case, rebuild with --clean or delete the output directory.
If you are running a QEMU image in headless mode, the console output is redirected to output/qemu.out. For VMware and VirtualBox, you can find the output from the commands used to start the virtual machine in .log files in the output directory.
If you get a build failure, a likely reason is changes you've made to one or more customization files. Any line numbers reported by mkifs or mkqnx6fsimg refer to files in the output/build.