Home > Articles > Operating Systems, Server

  • Print
  • + Share This

Customizing the Build Using Environment Variables

Once a Platform has been defined, you can use it to produce builds of the operating system that vary slightly in flavor without having to change the underlying definition of the platform. For example, you could choose to build Adam with a different display driver (either an S3 ViRGE or a Chips & Technologies CT65555) or choose to omit support for audio altogether. Such modifications to a platform are made dynamically through environment variables.

You can set environment variables in Platform Builder by selecting the Platform | Settings... menu item and then clicking on the Environment tab. Most, although not all, of the environment variables carry the prefix IMG. This prefix is short for image, which refers to the binary image of the operating system. IMG variables modify the way in which the image is built. The variables available in the Environment tab are listed in Table 3.5. To take effect, these variables must be defined. You can set up the definition by simply setting the variable to 1. Most variables work in a negative fashion. When set, they have the effect of not including a component or module. These variables have the word NO in their names and can be particularly confusing to use.

Table 3.5  Environment Variables Used by Platform Builder

Environment Variable

Usage

Description

FBBPP

Sets the number of bits per pixel on the display supported by the platform. This value is usually set to FB16BPP to indicate a display of 16 bits per pixel.

When FBBPP is set, the display drivers in the CEPC platform display drivers (S3 ViRGE, S3 Trio64, CT65555x, and so on) compile themselves for a pixel depth of 16; otherwise the default depth of 8 bits per pixel is used.

IME

Selects the type of Input Method Manager (IME) bundled with the platform. If the value of this variable is PIME, the Pocket IME version is added to the image. Pocket IME does not contain a user interface. If the value of this variable is TESTTIME, support that allows you to create your own IME is added to the image. The default value is IME98, which adds an IME with a user interface that mimics the full-blown Win32 API IME.

The value of IME is checked for the configuration file common.bib, and depending on its value, corresponding modules are added to the image.

IMGACMSAMPLES

Adds the sample codec driver (cegsm.dll) and the sample filter driver (msfilter.dll) to the image.

The value of IMGACMSAMPLES is checked in the project-specific configuration file project.bib. If the value is defined, the corresponding sample drivers are added to the image. However, the only project in Platform Builder 2.12 that supports this behavior is the MINSHELL project. Changing this value in our sample platform Adam will have no effect because it is derived from MAXALL.

IMGBIGFLASH

Configures the image to utilize a larger area of flash memory (an additional 8MB of flash is assumed).

IMGBIGFLASH is used in config.bib as a conditional to lay out the image to use the additional 8MB. This conditional is used only for the Odo platform. Hence, it doesn't affect Adam because Adam is derived from the CEPC platform.

IMGCOM2

Configures COM2 on the platform at 0x3E8.

IMGCOM2 is used in platform.reg, which initializes the system registry with platform-specific information.

IMGCOM3

Configures COM3 on the platform at 0x2E8.

IMGCOM3 is used in platform.reg, which initializes the system registry with platform-specific information.

IMGCOMMDEMOS

Adds two sample communication programs—ping.exe and ipconfig.exe—to the image.

IMGCOMMDEMOS is used in common.bib, which specifies the CE system files included in the operating system image.

IMGCTLPNL_G

Unknown

 

IMGDUB

Leaves additional space in the image layout to include the CE dial-up boot loader (DUB). The DUB is a component that can be used to upgrade the operating system image.

IMGDUB is used in config.bib to make space for the DUB file in the image layout. It is used only in the config.bib file for the Odo platform; hence, it doesn't affect Adam because Adam is derived from CEPC.

IMGEBOOT

Adds support for Ethernet debugging by bundling the Ethernet boot loader in the image.

IMGEBOOT is used in config.bib to make space for Ethernet debugger modules. It is used only in the config.bib file for the Odo platform.

IMGFLASH

Lays out the image in flash memory as opposed to RAM.

IMGFLASH is used in config.bib to make space for Ethernet debugger modules. It is used only in the config.bib file for the Odo platform.

IMGICONPOSITIONS

Allows explicit positioning of icons on the desktop as opposed to automatic positioning set by the shell.

Not used.

IMGMOREAPPS

Allows additional applications to be added to the image.

Not used.

IMGMORERAM

Lays out the image to simulate less area for ROM and release it for use as RAM area.

IMGMORERAM is used in config.bib to allocate more space to the RAM section. Use this setting if your image is relatively small (less than 6MB). The total memory assumed in the system is 32MB.

IMGMOREROM

Lays out the image to simulate less area for R<K>AM <K>and release it for use as ROM area.

IMGMOREROM is used in config.bib to allocate more space to the ROM section. Set this variable if your image is large (more than 6MB but less than 20MB). The total memory assumed in the system is 32MB.

IMGMOREROM16

Used just like IMGMOREROM, but when total memory in the system is assumed to be 16MB.

 

IMGNOBROWSER

Excludes Internet browser components in the operating system. Since Windows CE Help uses browser components, also disables Help. We are now in NO territory, so note that not defining this variable causes components to be added. The same goes for the NO variables that follow.

IMGNOBROWSER is used (1) in wceshell.bib to add the Pocket Internet Explorer files iexplore.exe, webview.dll, and imgdecmp.dll; (2) in wceshell.reg to specify browser proxy, start and search pages, and file associations; and (3) in wceapps.bib to ensure that browser components are bundled before Help is added.

IMGNOCEDDK

Excludes the CE DDK library in the image. The CE DDK library provides a processor-independent interface to the kernel, memory, and I/O to device drivers.

IMGNOCEDDK is used (1) in common.bib to include ceddk.dll in the image, and (2) in platform.bib for the CEPC platform to include the file pc_ddk.dll and rename it as ceddk.dll. The latter directive overrides the former when the image is being built.

IMGNOCOMM

Excludes all communications components in the image.

IMGNOCOMM is used in common.bib to include communication-specific components in the image.

IMGNOCONN

Excludes the components repllog.exe and rapisrv.exe, which communicate with Windows CE Services, which provide connectivity to a server (referred to as a desktop). An example of such an application is ActiveSync.

IMGNOCONN is used (1) in common.bib include the components, and (2) in to common.reg, where it is used to set up a registry entry that specifies the version of the modules. You must successfully negotiate this version number when you're communicating with a desktop.

IMGNOCONSOLE

Excludes the console support component console.dll and the console command language processor cmd.exe in the image.

IMGNOCONSOLE is used in common.bib to include the components.

IMGNOCTLPNL

Excludes the control panel and all applicable control panel applets in the image.

IMGNOCTLPNL is used in wceshell.bib to include the components. It is used in wceshell.reg to set up registry entries that describe the control panel color scheme and specify default settings for the various control panel applets.

IMGNODEBUGGER

Builds an image with a kernel debugger. Kernel debugging enables the kernel on the target to communicate with the kernel-debugging tool in Platform Builder. Extensive traces are also displayed by the kernel debugger.

IMGNODEBUGGER is used in common.bib to include either the kernel with debugging (nk.exe) or the kernel without debugging (nknodbg.exe) in the image.

IMGNODRIVERS

Excludes certain common drivers from the image.

IMGNODRIVERS is used in common.bib to include the parallel port and printer drivers (prnport.dll, prnerr.dll, pcl.dll), PC card ATA and IDE driver (atadisk.dll), PC card static RAM (SRAM) driver (sramdisk.dll), PC card linear flash driver (trueffs.dll), dual serial driver (dualio.dll) and waveform audio driver (waveapi.dll).

IMGNOETHER

Includes Ethernet support in the image.

IMGNOETHER is used in common.bib to include Address Resolution Protocol driver (arp.dll), NDIS driver (ndis.dll), NE2000-compatible card driver (ne2000.dll), Proxim RangeLAN PC card driver (proxim.dll), Xircom PC card driver (xircce2.dll), and Dynamic Host Configuration Protocol driver (dhcp.dll).

IMGNOFILES

Excludes certain files depending on context.

IMGNOFILES is used (1) in wceshell.bib to include desktop shortcuts (LNK files) and help files for shell components that have been included in the image, (2) in project.bib for the project MAXALL to include WAV files for system sounds, and (3) in wceapps.bib to include the shortcuts and help files for applications that have been included in the image.

IMGNOFLTDDK

See IMGNOCEDDK.

 

IMGNOHELP

Excludes Windows CE Help in the operating system.

IMGNOHELP is used (1) in wceshell.bib to include help components (part of the shell), (2) in wceshell.reg to include registry entries that set up help file associations with the appropriate modules, (3) in wceapps.bib to include help for components included in the image, and (4) in wceapps.reg to include registry entries in a manner similar to wceshell.reg.

IMGNOIDE

Not used.

 

IMGNOIE

Excludes Pocket Internet Explorer and support components.

IMGNOIE is used in ie.bib to exclude localization support for Internet Explorer (mlang.dll), ieceext.dll, shlwapi.dll, WinInet API (wininet.dll), URL and Moniker support (urlmon.dll), HTML support (mshtml.dll), HTML frames support (shdocvw.dll), limited XML support (msxml.dll), and mmefx.dll.

IMGNOJAVA

Excludes Java support from the operating system.

IMGNOJAVA is used in common.bib to exclude the Java modules cejvm.dll, jview.dll, ce_awt.dll, ce_local.dll, ce_math.dll, ce_irda.dll, ce_zip.dll, ce_net.dll, jcls.dll, and verifier.dll.

IMGNOJSCRIPT

Excludes JavaScript support from the operating system.

IMGNOJSCRIPT is used (1) in common.bib to exclude jscript.dll, and (2) in common.reg to set up OLE IDs for the JScript component in the system registry.

IMGNOLOC

Not used. Localization support is not optional.

 

IMGNOMAIL

Excludes Pocket Mail, Internet Message Access Protocol (IMAP), and Simple Mail Transport Protocol (SMTP) support.

IMGNOMAIL is used (1) in wceapps.bib to exclude pmail.exe, imap4.dll, smtp.dll, msgstore.dll, tnefutil.dll, mailutil.dll, labledit.dll, uicom.dll, and pimprint.dll; and (2) in wceapps.reg to set up registry entries for Pocket Mail.

IMGNOMLANG

Excludes localization support from Pocket Internet Explorer.

IMGNOMLANG is used in ie.bib to exclude mlang.dll.

IMGNOMSHTML

Excludes HTML support from the operating system.

IMGNOMSHTML is used in ie.bib to exclude mshtml.dll.

IMGNONETUI

Excludes the network user interface from the operating system. The network user interface allows manipulation of the configuration properties of the network via the Communication control panel applet.

IMGNONETUI is used in common.bib to exclude netui.dll.

IMGNOOLE32

Disables OLE support in the operating system.

IMGNOOLE32 is used in common.bib to exclude the OLE support components ole32.dll and oleaut32.dll.

IMGNOPCMCIA

Disables PC card support in the operating system. This entry doesn't exclude PC card support in the cards. operating system. It includes it but disables it at runtime. To exclude PC card support, you must exclude the file pcmcia.dll from the image (see ODO_NOPCMCIA).

IMGNOPCMCIA is used in common.reg to exclude registry entries for all supported PC

IMGNOPWORD

Excludes Pocket Word from the operating system.

IMGNOPWORD is used (1) in wceapps.bib to exclude office.dll, pwd_res.dll, pwwiff.dll, and pword.exe; and (2) in wceapps.reg to set up registry entries that define OLE IDs and file associations for Pocket Word.

IMGNOREDIR

Excludes network redirector support from the operating system.

IMGNOREDIR is used in common.bib to exclude the redirector components redir.dll and netbios.dll.

IMGNOSECURITY

Excludes security components from the operating system.

IMGNOSECURITY is used in common.bib to exclude the digital signature and data certificates (rsabase.dll) and the corresponding 128-bit version (rsaenh.dll).

IMGNOSERVERS

Excludes all servers from the operating system. If you plan to ship two different versions of your OS build (à la NT workstation and server), you can use this variable to switch between the versions.

IMGNOSERVERS is used in msmq.bib to exclude Microsoft Message Queue components msmqd.dll, netregd.dll, mqoa.dll, msmqadm.exe, and msmqrt.dll.

IMGNOSHDOCVW

Excludes HTML frames support from Pocket Internet Explorer.

IMGNOSHDOCVW is used in ie.bib to exclude shdocvw.dll.

IMGNOSHELL

Excludes the Windows CE shell and related components, shortcuts, and help files from the operating system. Excluding shell components automatically excludes the browser and CE Help.

IMGNOSHELL is used (1) in wceshell.bib to exclude the task manager (taskman.exe), asform.dll, the CE shell support component (ceshell.dll), and the explorer shell (explorer.exe); (2) in wceshell.reg to create registry entries that automatically launch the task manager and explorer shell on startup; (3) in wceapps.bib to exclude browser and help files if set; and (4) in wceapps.reg in the same way as in wceshell.reg.

IMGNOTXTSHELL

Excludes the CE shell from the operating system. The CE shell communicates with a designated desktop for debugging and synchronization services.

IMGNOTXTSHELL is used in common.bib to exclude the CE shell components cesh.dll and toolhelp.dll.

IMGNOURLMON

Excludes URL and Moniker support from the browser.

IMGNOURLMON is used in ie.bib to exclude urlmon.dll.

IMGNOWININET

Excludes WinInet API support from the operating system.

IMGNOWININET is used in ie.bib to exclude wininet.dll.

IMGNSCFIR

Includes the National Security Council Fast Infrared driver.

IMGNSCFIR is used in platform.bib for the CEPC platform to include nscirda.dll (if not set, the regular IrDA driver irsir.dll is included), and (2) in platform.reg to set up registry entries for the appropriate IrDA driver included in the operating system.

IMGPROFILER

Builds a profile-enabled kernel in the operating system.

IMGPROFILER is used (1) in common.bib to include the profile-enabled kernel nkprof.exe in the image, and (2) in config.bib for the CEPC and Odo platform to instruct the OS build tool that profiling has been enabled in the kernel (PROFILE=ON).

IMGSTRICTLOC

Not used.

 

IMGTINY

Builds a special bare-bones version of the operating system.

IMGTINY is used in common.bib, wceshell.bib, wceapps.bib, wceapps.bib, and the platform.bib files for the CEPC and Odo platforms.

IMGTINYFSRAM

Uses a (relatively) tiny percent of RAM for the file system. By default, CE uses the RAM for file system storage.

IMGTINYFSRAM is used in config.bib to set another variable, FSRAMPERCENT, to the hex value of 80. This number instructs CE to use only 50 percent of the first 1MB of RAM for the file system.

IMGUSB

Adds USB support to the operating system

IMGUSB is used in platform.bib for the CEPC platform to include the USB support components Open Host Controller Interface driver (ohci.dll), USB driver (usbd.dll), and USB mouse driver (usbmouse.dll).

IMGUSEPROXY

Enables the use of a proxy server for HTTP.

IMGUSEPROXY is used in wceshell.reg to add lines to the system registry that instruct the browser to use a proxy server called itgproxy for HTTP access on port 80. Edit these settings to configure your own proxy server by name if you turn on this variable.

INITNOCOMM

Disables the NDIS and auxiliary function driver (AFD) protocol manager at runtime.

INITNOCOMM is used in common.reg to disable the registry settings for the NDIS and AFD components. Note that this setting does not remove ndis.dll and afd.dll from the image. It allows the components to be part of the image but simply disables them at runtime.

SCHEDLOG

Includes the scheduler log functions in the operating system.

Scheduler log functions are implemented in schedlog.dll and are used as helper functions when thread and process logging are being implemented in the kernel. SCHEDLOG is used in the Sources file for the kernel modules in CEPC and Odo platforms to link the kernel with schedlog.lib. In the Sources file for the Hardware Abstraction Layer (HAL), this variable is used to pass -D SCHEDLOG to the compiler. This flag is used to conditionally add a HAL IOCTL (I/O control) code that enables scheduler logging.

TESTSIP

Includes the Software Input Panel (SIP) control panel applet in the operating system. The applet is used to configure the SIP, a keyboard implemented in software for devices that do not have a keyboard (e.g., the Palm-size PC).

TESTSIP is used (1) in common.bib to include the SIP control panel applet (msim.dll), and (2) in common.reg to specify default values for SIP configuration (manipulated by msim.dll).

WINCEPROFILE

Builds a version of the kernel that supports profiling.

WINCEPROFILE is used in the HAL Sources file for the CEPC platform to pass the -D PROFILE flag to the compiler. This flag is not really used by the HAL, since a kernel with profile information is always built (nkprof.exe). However, you can use conditional compiling around the constant PROFILE to add any profile-specific code to the HAL.


Environment variables also find use in customization of the base platform chosen to build a new platform. For example, we chose MAXALL to build Adam. Now we can modify the MAXALL configuration for use in Adam by changing the value of these environment variables appropriately.

These variables can also be put to good use during development and debugging. It may not be necessary for every developer on the project to include all components of the operating system. A developer working on writing a PC card driver for a bar code scanner may not need to include any of the Pocket applications like Explorer and Mail, the serial port driver, or communication components. Such choices can help reduce the size of the operating system image being built, which is instrumental in shorter download times to the hardware platform, resulting in a more rapid development cycle.

Of course, when the driver is finally ready, the developer must test it with the full build of the operating system that is expected to run on the hardware platform.

  • + Share This
  • 🔖 Save To Your Account

Related Resources

There are currently no related titles. Please check back later.