netbeans.apache.org/src/content/wiki/DevFaqWhatIsNbm.asciidoc

// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you under the Apache License, Version 2.0 (the
//     "License"); you may not use this file except in compliance
//     with the License.  You may obtain a copy of the License at
// 
//       http://www.apache.org/licenses/LICENSE-2.0
// 
//     Unless required by applicable law or agreed to in writing,
//     software distributed under the License is distributed on an
//     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
//     KIND, either express or implied.  See the License for the
//     specific language governing permissions and limitations
//     under the License.
//

= DevFaqWhatIsNbm
:jbake-type: wiki
:jbake-tags: wiki, devfaq, needsreview
:jbake-status: published
:keywords: Apache NetBeans wiki DevFaqWhatIsNbm
:description: Apache NetBeans wiki DevFaqWhatIsNbm
:toc: left
:toc-title:
:syntax: true

=== What is an NBM?

An NBM file is a NetBeans module packaged for delivery via the web.
The principal differences between it and a module JAR are:

* It is compressed
* It can contain more than one JAR file - modules can package any libraries or other files they use into their NBM
* It contains metadata NetBeans will use to display information about it in the update center, such as the manifest contents, the license, etc.
* NBMs may be signed for security purposes

NBM files are just ZIP files with a special extension,
which use the JDK's mechanism for signing JARs.
Unless you're doing something unusual, you will not need to worry about the contents of NBMs -
just let the standard Ant task for NBM creation take care of it for you.
For those interested in gory details, read on.

==== Structure of an NBM

Below is an example of the contents of one -
this is from the `hexedit_integration` module in `contrib`,
which packages up an external library as well:

`Info/info.xml`:Metadata - this file is generated by the standard NBM build target, so if you use NetBeans support for creating modules, you should not need to do anything special to create it.  This info is used by the IDE to figure out if a module the user is installing is newer or older, than an existing one, whether or not its dependencies can be satisfied, etc. `META-INF/MANIFEST.MF`:The manifest - usually nothing of interest here, it is just generated because NBMs are created the same way that JARs are. May point to a signature for the NBM.`netbeans/....`:Contents to be unpacked to some cluster in the NetBeans installation (or the user directory).`netbeans/config/Modules/org-netbeans-modules-hexeditor.xml`:The module XML file used at runtime to discover modules. Indicates whether the module is autoload, etc.`netbeans/modules/org-netbeans-modules-hexeditor.jar`:The actual module JAR.`netbeans/modules/ext/hexedit.jar`:A library this module uses and includes.

Since NetBeans 6.9 NBM files now supports pack200 compression and all jar files in NBMs becomes compressed and have ".pack.gz" appended to the name e.g. modules/org-netbeans-modules-hexeditor.jar.pack.gz. 

For more info about pack200 usage see link:DevFaqNBMPack200.asciidoc[DevFaqNBMPack200].

==== Runtime module XML metadata

The `org-netbeans-modules-hexeditor.xml` runtime metadata file looks like this:

[source,xml]
----

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module PUBLIC "-//NetBeans//DTD Module Status 1.0//EN"
                        "http://www.netbeans.org/dtds/module-status-1_0.dtd">
<module name="org.netbeans.modules.hexeditor">
    <param name="autoload">false</param>
    <param name="eager">false</param>
    <param name="enabled">true</param>
    <param name="jar">modules/org-netbeans-modules-hexeditor.jar</param>
    <param name="release">1</param>

    <param name="reloadable">false</param>

    <param name="specversion">1.0</param>

</module>


----

==== Module installation metadata - Info.xml

The `Info/Info.xml` file that NetBeans uses to figure out if it _can_ install a module,
dependencies, etc.  looks like this
(it also contains the license that the user will agree to to install the module from the update center):

[source,xml]
----

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module PUBLIC "-//NetBeans//DTD Autoupdate Module Info 2.3//EN"
                        "http://www.netbeans.org/dtds/autoupdate-info-2_3.dtd">
<module codenamebase="org.netbeans.modules.hexeditor"
        homepage="http://contrib.netbeans.org/"
        distribution="http://...../org-netbeans-modules-hexeditor.nbm"
        license="standard-nbm-license.txt"
        downloadsize="0"
        needsrestart="false"
        moduleauthor=""
        releasedate="2005/08/29"
>
  <manifest OpenIDE-Module="org.netbeans.modules.hexeditor/1"
            OpenIDE-Module-Display-Category="Infrastructure"
            OpenIDE-Module-Implementation-Version="050829"
            OpenIDE-Module-Long-Description="Sample module hexeditor providing HexEdit"
            OpenIDE-Module-Module-Dependencies="org.openide.filesystems > 6.2, ..."
            OpenIDE-Module-Name="hexeditor"
            OpenIDE-Module-Requires="org.openide.modules.ModuleFormat1"
            OpenIDE-Module-Short-Description="Sample hexeditor module"
            OpenIDE-Module-Specification-Version="1.0"
  />
  <license name="standard-nbm-license.txt"><![CDATA[
                Sun Public License Notice
....
]]></license>
</module>

----

<hr/>

Applies to: NetBeans 6.5 and above

=== Apache Migration Information

The content in this page was kindly donated by Oracle Corp. to the
Apache Software Foundation.

This page was exported from link:http://wiki.netbeans.org/DevFaqWhatIsNbm[http://wiki.netbeans.org/DevFaqWhatIsNbm] , 
that was last modified by NetBeans user Jtulach 
on 2010-07-16T08:13:22Z.


*NOTE:* This document was automatically converted to the AsciiDoc format on 2018-02-07, and needs to be reviewed.