The Java JAR Manifest file MANIFEST.MF

A Java JAR may contain a file META-INF/Manifest.mf. This file contains metadata about the JAR itself. It can be automatically created by the build tool. Ant has special support for generating valid manifest files.

Features

• A standard format for representing metadata about a JAR file.
• Documented in the JAR File Specification
• Contains security information about signed classes in the JAR
• Can contain an index of all classes in the JAR (and dependent JARs), for faster location of dependent libraries.
• Can contain the classpath of other JAR files (using relative/absolute filenames) for this JAR to load.
• Standard syntax for unicode characters.
• Standard line length: 72 characters
• Standard encoding: UTF-8
• Standard rules for wrapping long lines. If the UTF-8 encoded line would exceed 72 characters, the line must be broken at the 72 character mark. The remainder of the value should continue on the following line, with a preceeding space to indicate that this is a continuation.
• Entries may not be duplicated, except for Class-Path: entries.

Advantages

• Very lightweight to parse: no need for an XML parser or similar. This makes it easier to embed Java into very small devices.

Disadvantages

• There is no utility API to read and write the manifest in the standard Java API, other than the Java Package class.
• the Java Package class has some behaviours that are not documented in the specification. Specifically, it requires META-INF and META-INF/MANIFEST.MF to be the first two files stored in the JAR. Ant bug report 3287

• There is no equivalent of an XML schema to validate the file, or any tool in the JDK that validates a manifest.
• Developers who implement their own code to read or write the manifest file often fail to read the specification adequately.
• Some J2ME implementations are very sensitive to the ordering of entries in the manifest, and do not handle wrapped lines.
• Some Application servers do not read files according to the rules [6076]
• Some IDEs do not read manifests according to the rules [37340]
• Most developers do now know the multiple-class path rule, which is not consistent with the rest of the system.
• Many developers do not know the subtleties of the line-wrapping logic.

The difference between expected behaviour and actual behaviour is a recurrent source of support calls in Ant. [9258, 3811, 12496, 10960, 22530, 7079, 31251]

Every so often, however, the reports are valid. There are also some ambiguities in interpretation that need to be resolved through bug reports and experimentation.

These bug reports are interesting, as they show how a relatively simple specification can still be hard to read and write. Too many programs treat it as a simple Properties File, when in fact it is something much more complex, with line wrapping, duplicate Class-Path entries and UTF-8 encoding. It is notable that XML files do not cause such problems at parse time, because nobody tries to implement their own XML parser. In XML, the problems are raised up from line-wrapping issues to those of semantics.

SmartFrog support

SmartFrog does not directly read or write manifest files. The sf-ant package can run the Ant <jar> and <manifest> tasks, which are the most thoroughly tested implementations on the planet outside Sun's own libraries.

Anyone wishing to implement their own parser for the SmartFrog language is encourage to learn the lessons of the MANIFEST.MF file. Use the syntax file /org/smartfrog/sfcore/languages/sf/DefaultParser.jj as a basis of a parser, rather than try and reverse engineer the syntax from the English-language specification.

Examples

Manifest-Version: 1.0
Ant-Version: Apache Ant 1.7
Created-By: 1.5.0_01-b08 (Sun Microsystems Inc.)
Main-Class: org.apache.tools.ant.launch.Launcher

This is a simple manifest with a main-class defined.

Manifest-Version: 1.0
Ant-Version: Apache Ant 1.7
Created-By: 1.5.0_01-b08 (Sun Microsystems Inc.)
Main-Class: org.apache.tools.ant.Main

Name: org/apache/tools/ant/
Extension-name: org.apache.tools.ant
Specification-Title: Apache Ant
Specification-Version: 1.7
Specification-Vendor: Apache Software Foundation
Implementation-Title: org.apache.tools.ant
Implementation-Version: 1.7
Implementation-Vendor: Apache Software Foundation

This is the main JAR; it has added an extension specification and implementation. In the past, the JAR declared a dependency on Xerces in its manifest; this has been disabled now that adequate XML parsers are more common in the Java runtime.

Manifest-Version: 1.0
Implementation-Version: 1.0.2
Specification-Title: JavaBeans(TM) Activation Framework Specification
Specification-Version: 1.0
Extension-Name: javax.activation
Created-By: 1.3.0 (Sun Microsystems Inc.)
Implementation-Vendor-Id: com.sun
Implementation-Vendor: Sun Microsystems, Inc.
Specification-Vendor: Sun Microsystems, Inc.
SCCS-ID: @(#)jaf.mf	1.1	02/03/15

Name: javax/activation/MimeTypeParseException.class
SHA1-Digest: uxV3qLHRu5JTOFrHnJXm13AO+0M=

Name: javax/activation/CommandInfo.class
SHA1-Digest: 1cKS/VKDQRQtAdvjQSJXZfjuKnM=

This manifest continues with a SHA1 digest for every class in the JAR.