Introduction to Cabarc

In this topic

Creating and Using Cabinet Files for Java Applets and Libraries Previous Tools Next

Introduction to Cabarc

Cabarc is a utility that creates, extracts, and lists the contents of cabinet (.cab) files. Cabarc uses a command-line interface similar to that of popular archiving tools. Cabarc supports wildcards and recursive directory searches.

The cabinet format is an efficient way to package multiple files. The cabinet format has two key features: multiple files can be stored in a single cabinet (.cab) file, and data compression is performed across file boundaries, which significantly improves the compression ratio. Cabinet file construction can be designed around the number of files to be compressed and the expected patterns for gaining access to them (sequential, random, all at once, or a few at a time).

A key concept of the cabinet file is the folder. A folder is a collection of one or more compressed files that are compressed together as a single entity. Compressing files this way improves the compression ratio. Random access time suffers, however, because decoding (decompressing) any file in a folder requires that all preceding files in that folder must also be decoded. The focus is on maximum compression as opposed to quick decompression, since the cabinet format is designed to deliver file content, rather than to stream media.

The dubuild utility is an alternative to cabarc when distributing software using Microsoft® Internet Explorer 4.0. The dubuild utility creates Distribution Units that are installed using the Java Language Package Manager. For more information, see Using DUBuild and Java Package Management and Code Download.

Using Cabinets With Java Files

There are two reasons to use the cabinet technology with Java classes. The first is building Java applets with lots of classes and graphics or audio files that you would like compressed and that would not be shared by other sites. This group is referred to here as the "applet" group, referring to the <APPLET> HTML tag that is used to access the contents of the cabinet file.

The second reason is to distribute your Java class libraries to users so that your classes can be accessed like system classes by Java applets or applications. HTML pages that download cabinets containing library files use the <OBJECT> tag to download and access the libraries. Note that the library scheme only supports the download and access of class files, not images or audio. These files should be provided by the applet and not the cabinet file.

Archiving Applets and Multimedia Files

This procedure will help you create a cabinet file for delivering compressed class and multimedia files to a user's system.

Make sure that the SDK-Java\Bin directory, which contains Cabarc.exe, is in your path.
Run Cabarc.exe to build a cabinet containing all of your files. See the section of this article for command-line syntax for the cabarc tool.
Optionally, digitally sign the cabinet file.
Code-signing is important for users, so that they know to trust your code before placing it on their computers. For the latest information on how to get your code signed, see the signcode article and http://www.microsoft.com/workshop

When creating cabinets that will be read by the browser from the CABBASE parameter, make sure to use the default compression mode (MSZIP) and not the new LZX (Lempel-Ziv) compression mode, which is not supported by Internet Explorer 3.xx, but is supported by Internet Explorer version 4.0).

Archiving Library Files

When delivering libraries in a cabinet file, the files to be compressed and delivered are archived in one cabinet file called the inner cabinet. This file is itself archived in another cabinet file (called the outer cabinet) with an .inf file. The .inf file, based on the Master.inf template found in the SDK-Java\Bin directory, is used by the setup engine in Internet Explorer. It contains the names of the libraries, where the libraries should be placed, the class identifier used in the <OBJECT> tag, and so on. The use of the .inf file only pertains to libraries, which are referenced by using the <OBJECT> HTML and does not pertain to applets.

Information for the Master.inf Template

For Java libraries, you will need to gather the following information to fill out the .inf file copied from the Master.inf template (found in the SDK-Java\Bin directory).

Decide whether to place the libraries in the Lib or TrustLib directory. In the .inf file, you will edit the lines that determine whether the libraries are placed in the <windir>\Java\Lib or <windir>\Java\TrustLib directory. Comment out the line that does not apply. The following code sample shows the default that is in Master.inf.
```
   ; If you use one of these, you will use exactly one.

   HKLM,"SOFTWARE\Classes\CLSID\%ClassId%\InProcServer32","Lib",,"%49000%"
   ;HKLM,"SOFTWARE\Classes\CLSID\%ClassId%\InProcServer32","TrustedLib",,"%49000%"
```
Include the name of the cabinet file that contains your classes. Replace CabFileName.cab with your class cabinet name in the following line.
```
    run=extrac32.exe /e /a /y /l %49000% CabFileName.cab
```

Include the name of the .inf file that you are using. Replace Master.inf with the name of your .inf file as indicated in the following code example.


    [hook2]

    ; Change the name of master.inf to the name you are assigning this
    ; file. Leave the second line alone.

    InfFile=master.inf
    InfSection=RegistryData

Include a unique ClassId, generated by running Guidgen.exe from the SDK-Java\Bin directory. The following code excerpt from the Master.inf template file sets the identifier.


    [Strings]
    ; Running guidgen in the SDK generates the ClassId you need to fill 
    ; in here. This classId also goes in the OBJECT tag.
    ; Don't forget the set braces!

    ClassId="{99999999-9999-9999-9999-999999999999}"

Include the name of your libraries. The following code excerpt from the Master.inf template file sets the library name.


    ; Put the name by which your packages should be referred to 
    ; (i.e., "Bob's Text Viewer") here.

    PackageName="name"

Should you want to, you can also include the following information.

A version number. Version numbers are in the form a,b,c,d (that is, 1,0,5,10). This prevents downloading the same library if the user has the latest version. (This is a recommended practice.) The following code excerpt from Master.inf sets the version number.


    ; Replace <aa...> with the version number (like 1,0,0,1) of this
    ; version of your library. This is so that when you want to update
    ; your libraries, you can change the version rather then the classId
    ; and the problems that go with that. If the version number here
    ; and in the OBJECT tag match the version already stored on the
    ; user's machine, it will not download the classes again, which
    ; also saves time and energy.

    HKLM,"SOFTWARE\Classes\CLSID\%ClassId%\InstalledVersion",,,"aa,bb,cc,dd"

A filename. This file can be examined by the browser to determine if the library files have already been installed on the system. This is illustrated in the following code example.


    ; Here, replace <file> with the name of one of the class files in
    ; your package, including the virtual path to that file. 
    ; This will make sure that the classes exist on the
    ; user's system; if they don't, they will be downloaded, regardless
    ; of version numbers.

    HKLM,"Software\Classes\CLSID\%ClassId%\InstalledVersion","Path",,"%49000%\<file>"

The names of any native code that you want to install from your cabinet file (the one containing the .inf and .cab file). These files are installed automatically in the <windir>\System directory. The following code excerpt from Master.inf sets the code names.



    ;; If you are installing native code, you will want to uncomment all
    ;; the lines in the remainder of this section, except for the ones 
    ;; that are descriptive (and have two semicolons).

    ; CopyFiles=OtherFiles

    ;[DestinationDirs]
    ;OtherFiles=11

    ;[OtherFiles]
    ;; List the name of each file (delimited by returns) here.
    ;; Just list the local name--no need for paths, and so on. Example:
    ;; foo1.dll,,,32
    ;; foo2.dll,,,32

    ;[SourceDisksFiles]
    ;; For each name listed in the above section, you will want to put
    ;; <filename>=1 on this list. So it would look like
    ;; foo1.dll=1
    ;; foo2.dll=1

    ;[SourceDisksNames]
    ;1=%PackageName%,"",0

Instructions for Building Cabinet Files for Libraries

The following steps will help you create a cabinet file for installing Java libraries on a user's computer.

Make sure that the SDK-Java\Bin directory, which contains Cabarc.exe, is in your path.
Run Cabarc.exe to build your cabinet containing all your class files. For command-line syntax for the cabarc tool, see the section of this document. It is a good ideato put your vendor name as the package name preceding all your classes to avoid having them overwritten by other installed classes. For example, your classes should be in the form suggested by the following example (where "vendor" is your unique vendor name).
```
		vendor.util.loader.class
		vendor.util.builder.class
		vendor.applet.start.class 
```
For example, say your company is called CoolTools. You have a package called "widgets" located on your development computer at c:\JavaCode\CoolTools\Widgets\*.class. You want to install this package in the user's <windir>\Windows\Java\Lib directory. You would change directory to c:\JavaCode\ and run cabarc as follows.
```
cabarc -r -p -P javacode\ n CTClasses.cab CoolTools\*.*
```
In this syntax, -r tells cabarc to recursively archive everything under CoolTools, maintain the directory structure (-p), strip off javacode from directories (-P javacode\), and create a cabinet file called CTClasses.cab.
When this is installed on the user's system, all classes would be placed under the <windir>\Java\Lib unless the .inf file was modified to place them in the TrustLib directory.
Make a copy of the Master.inf template in the SDK-Java\Bin directory and edit the copy. This sets up the layout and instructions for installing the libraries. The Master.inf file is heavily commented and includes places to put the information you have gathered. For details about what goes into this file, see Information for the Master.inf Template.
Remember to run the guidgen tool to create a ClassId and copy it into the correct place in the .inf file.
Following on with the CoolTools example, you would create a file (for example, Cool.inf) based on Master.inf, create a ClassId using guidgen, copy it into the file, and then edit the name of the .inf file and the .cab file in Cool.inf.
The following code excerpt from the Cool.inf file shows the mandatory edits that must be made.
```
[hook1]

; In this line, replace CabFileName.cab with the your CAB filename.

run=extrac32.exe /e /a /y /l %49000% CTClasses.cab 

[hook2]

; Change the name of master.inf to the name you are assigning this
; file. Leave the second line alone.

InfFile=cool.inf
InfSection=RegistryData


[Strings]
; Running uuidgen in the SDK generates the ClassId you need to fill 
; in here. This classId also goes in the OBJECT tag.
; Don't forget the set braces!

ClassId="{4439E200-6FCC-11d0-89AA-00A0C9054129}"

; Put the name by which your packages should be referred to 
; (i.e. "Bob's Text Viewer") here.

PackageName="CoolTool Java Classes"
```
Run Cabarc.exe again. This step builds the cabinet file containing the class cabinet, the .inf file, and any other files you might want to include. The following example demonstrates how to create a cabinet file called CoolDown.cab, which includes the Cool.inf and the CTClasses.cab files.
```
       cabarc  n CoolDown.cab CTClasses.cab Cool.inf 	
```
Digitally sign the cabinet file.
Code-signing is important for users, so that they know to trust your code before placing it on their computers. The default settings in Internet Explorer will reject unsigned code. For the latest information on how to get your code signed, see the signcode article and http://www.microsoft.com/workshop/.

Accessing the Cabinet From a Web Page

For Java applets, you use the CABBASE parameter in an APPLET tag to point to the .cab file. If the applet is not already present on the user's system, the .cab file is downloaded, the contents are extracted, and the applet is started.

To use the APPLET tag, you set the parameters as shown in the following example.


<APPLET CODE="sample.class" WIDTH=100 HEIGHT=100>
<PARAM NAME="cabbase" VALUE="vendor.cab">
</APPLET>

Using the CABBASE parameter does not conflict with CODEBASE or any other parameters necessary for other browsers. Using CABBASE along with the other tags allows Internet Explorer 3.0 and other cabinet file-supporting browsers to use .cab files without impeding the ability of other browsers to download and execute applets.

For Java libraries, you use the OBJECT tag to point to the .cab file. If the classes (in the current version) are not already present on the user's system, the .cab file is downloaded, and the contents are extracted and placed in the appropriate location on the user's system. This step should be done according to following syntax.


<OBJECT CLASSID="<classid>" CODEBASE="<path to cab>#Version=x,x,x,x">
</OBJECT>

For example,


<OBJECT 
    CLASSID="clsid:12345678-9abc-def1-1234567890ab" 
    CODEBASE="cabs/vendor.cab#Version=1,0,0,12">
</OBJECT>

As in the preceding example, the CODEBASE attribute can specify a version number, which enables the libraries to be downloaded and installed if the version on the user's system is out-of-date.

Both the ClassId and the version number are also stored in the .inf file inside the outer cabinet file. Including the version number is optional but highly recommended. This step permanentlyinstalls the classes on the user's system, so only use this for libraries.

After libraries are installed in this manner, APPLET tags can refer to the classes placed in the library specified by Cabs/Vendor.cab. Those applets work like normal, with classes brought in through CABBASE or CODEBASE.

Using the Cabarc Utility

Cabinets are created by using the n command, which is followed first by the name of the cabinet to create and then by a filename list. This is shown in the following example.

cabarc n mycab.cab prog.c prog.h prog.exe readme.txt

The previous command creates the cabinet Mycab.cab containing the files Prog.c, Prog.h, Prog.exe, and Readme.txt in a single folder by using the default compression mode, MSZIP.

Command Line Usage

Cabarc is used as follows.

cabarc [<options>] <command> [<file list>]

Three commands are currently supported: n (creates a new cabinet), l (lists the contents of an existing cabinet), and x (extracts files from a cabinet). These commands are described later in this document.

Using Wildcards

Cabarc supports wildcards in the filename list, as shown in the example below.

cabarc n mycab.cab prog.* readme.txt

Creating Folders

All files are added to a single folder (compression history) in the cabinet. It is possible to instruct cabarc to begin a new folder by using the plus sign (+) for the file to be added, as shown in the following example.

cabarc n mycab.cab test.c main.c + test.exe *.obj

The previous command creates the cabinet mycab.cab with one folder containing test.c and main.c and a second folder containing test.exe and all files matching *.obj.

Preserving Directory Paths

By default, directory names are not preserved in the cabinet—only the filename component is stored. For example, the following command stores prog.c in the cabinet.

cabarc n mycab.cab c:\source\myproj\prog.c

To preserve paths, use the -p option as shown in the following example.

cabarc -p n mycab.cab c:\mysource\myproj\prog.c

This command puts mysource\myproj\prog.c in the cabinet. Be aware that the c:\ prefix is still stripped from the filename. Cabarc will not enable absolute paths to be stored in the cabinet, nor will it extract such absolute paths.

Stripping Paths

Path stripping is an option that preserves part of a path name. The following example shows how the path stripping option can archive everything in the c:\mysource\myproj\ directory but store only the myproj\ component of the path.

cabarc -p -P mysource\ n mycab.cab c:\mysource\myproj\prog.c

The -P option strips any strings that begin with the string provided. Be aware that wildcards are not supported by the -P option, which is a simple text match. Absolute path prefixes, such as c:\ or \, are stripped before the comparison takes place. Do not include absolute path prefixes when using the -P option.

The -P option may be used more than once to strip out multiple paths. Cabarc builds a list of all paths to be stripped and applies only the first one that matches. Consider the following example.

cabarc -p -P mysrc\ -P yoursrc\ n mycab.cab c:\mysrc\myproj\*.* d:\yoursrc\yourproj\*.c

The trailing slash at the end of the path name is important. Entering -P mysrc instead of -P mysrc\ would cause files to be added as \myproj\<filename>.

Using Recursive Directory Search

Cabarc can archive files in a directory and all of its subdirectories by using the -r option. For example, the following command example archives all files ending in .h that are in c:\msdev\include\, c:\msdev\include\sys, and c:\msdev\include\gl (assuming these directories exist on your system).

cabarc -r -p n mycab.cab c:\msdev\include\*.h

The -p option is used here to preserve the path information when the files are added to the cabinet. Without this option, only the filename components would be stored, although sometimes it might be desirable behavior to not use -p.

Reserving Space for Code Signature

Cabarc can reserve space in the cabinet for a code signature. This is done with the -s option, which reserves a specified amount of empty space in the cabinet. For code signatures, reserve 6144 bytes. Consider the following example for doing so.

cabarc -s 6144 n mycab.cab test.exe

Be aware that the -s option does not actually write the code signature; it merely reserves space for it in the cabinet. Use the appropriate code signing utility to fill out the code signature.

Setting the Cabinet ID

Cabinet files have a 16-bit cabinet ID field that is designed for application use. The default value of this field is zero; however, use the -i option of cabarc to set this field to any 16-bit value. Consider the following example.

cabarc -i 12345 n mycab.cab test.exe

Setting the Compression Type

Set the compression type with the -m option. The default compression type for a cabinet is MSZIP . The three supported compression modes are MSZIP compression (-m MSZIP), no compression (-m NONE), and LZX compression. LZX compression is selected by -m LZX:<w> where <w> is a number in the 15 to 21 range denoting the size of the compression history window, 2 to the power of <w>. A larger history window requires more memory when compressing or decompressing, but it provides better compression. LZX compression must not be used when creating cabinets that will be read by the browser from the CABBASE parameter—Internet Explorer 3.xx does not support the LZX compression mode. However, Internet Explorer version 4.0 does.

The following command stores files in the cabinet with MSZIP compression.

cabarc -m MSZIP n mycab.c *.*

Using a File List from a File

Cabarc can input its list of files from a text file instead of from the command line by using the @file option followed by the name of the file from which to take the inputs. Consider the following example.

cabarc n mycab.cab @file filelist.txt

The text file must list the physical filenames of the files to be added, one per line. As is the case when specifying filenames on the command line, the plus sign (+) can be used as a filename to specify the beginning of a new folder. If a filename contains any embedded spaces, it must be enclosed as quotes, as follows.


test.c
myapp.exe
"output file.exe"

Quotation marks are required because each physical filename can be followed (on the same line) by an optional logical filename, which specifies the name under which the file will be stored in the cabinet. Consider the following example.


test.c myapp.c
myapp.exe
"output file.exe" myfile.exe

If the logical filename contains spaces, it also must be enclosed in quotation marks. Note that the logical filename overrides the -p (preserve path names) and -P (strip path name) options; the file is added to the cabinet exactly as indicated. Wildcards can be used in the physical filename, but in this situation, a logical filename is not allowed.

The @file option can be used more than once to retrieve file lists from multiple files. Cabarc does not check for the presence of duplicate files, so if the same physical file appears in more than one file list, the file will be added to the cabinet as often as needed.

The @file option can be combined with filenames on the command line. The files from the use of -l option are added first. Consider the following example.

cabarc -l filelist1.txt -l filelist2.txt n mycab.cab *.c *.h

Note that the @file option is available only when creating cabinets, not when extracting or listing cabinets.

Listing Cabinet Contents

It is possible to view the contents of a cabinet using the l (list) command, as shown below.

cabarc l mycab.cab

Cabarc displays the cabinet identifier in the cabinet. (See the -s option for cabinet creation.) Cabarc also displays the following file information: size, date, time, and attributes.

Extracting Files from Cabinets

The x (extract) command extracts files from a cabinet. The simplest use of the X command is shown in the following example, which extracts all files from the cabinet.

cabarc x mycab.cab

Alternatively, it is possible to extract files selectively by providing a list of filenames, wildcards, or both.

cabarc x mycab.cab readme.txt *.exe *.c

Full path names (if they are present in the cabinet) are not preserved upon extraction by default. For example, if a file named mysrc\myproj\test.c is present in the cabinet, the command cabarc x mycab.cab will cause the file test.c to be extracted into the current directory. To preserve filenames upon extraction, the -p option must be used. The -p option causes any required directories to be created, if necessary.

Only the filename component is considered in the matching process. The path name is ignored. For example, the command "cabarc x mycab.cab test.c" causes the file mysrc\myproj\test.c to be extracted to the current directory as test.c, as will cabarc x mycab.cab *.c (which also extracts any other files matching *.c).

By default, the extracted files are stored in the current directory (and its subdirectories, if the -p option is used). However, it is possible to specify a destination directory for the extracted files. This is accomplished by appending a directory name to the command line. The directory name must end in a backslash (\). Consider the following examples.


cabarc x mycab.cab c:\somedir\
cabarc x mycab.cab *.exe c:\somedir\