WorkingWithNetBeansSources

(Difference between revisions)
(Tools)
(Mercurial access: remote: ssl required)
 
(27 intermediate revisions not shown)
Line 1: Line 1:
-
__NOTOC__
 
So you want to tinker with the code, build the whole IDE from sources, implement features yourself?  This is the minimum
So you want to tinker with the code, build the whole IDE from sources, implement features yourself?  This is the minimum
to get you started.
to get you started.
-
If you are interested in sources for NetBeans 6.0 or earlier, see: [[WorkingWithNetBeansSourcesPre61 | WorkingWithNetBeansSourcesPre61]]
+
If you are interested in sources for NetBeans 6.0 or earlier, see: [[WorkingWithNetBeansSourcesPre61]]
-
===Tools===
+
=Tools=
-
You need the following to be installed on your machine
+
You need the following to be installed on your machine:
-
* JDK 6 for NetBeans 6.9 or newer, JDK 5 for NetBeans 6.8 or older (it '''must be 1.5.0''' because NetBeans must be runnable on this version of JDK or newer, by using 1.5.0 you will ensure that you don't use APIs and features available only in JDK 6 or newer)
+
* JDK 8
-
* Apache Ant 1.7.1
+
** JDK 8 is required to build NetBeans sources after NetBeans 8.1
-
* Latest Mercurial release (at least 1.0.2), presupposing Python 2.5.1 or later
+
** ''JDK 7 you can still use for compiling of sources NetBeans 8.1 to 7.4''
 +
** ''JDK 6 you can still use for compiling of sources NetBeans 7.3 or older''
 +
* Recent Apache Ant release (1.9.6 is current as of this writing)
 +
* Recent Mercurial release (3.6 is current as of this writing), presupposing Python 2.5.1 or later
 +
Running <tt>ant</tt> at the root of the source tree should suffice to build the complete IDE.
The whole source tree has NetBeans project metadata so you can just use NetBeans to develop NetBeans.
The whole source tree has NetBeans project metadata so you can just use NetBeans to develop NetBeans.
 +
For example, open any module project (top-level directory), make some edits, and click Run Project to try the IDE with your modifications.
-
===Mercurial access===
+
=Mercurial access=
-
<pre>
+
<source lang="bash">
-
hg clone http://hg.netbeans.org/main-silver/
+
$ hg clone http://hg.netbeans.org/main-silver/
-
</pre>
+
</source>
-
(If you are going to be pushing changesets directly, you will be cloning a team repository instead.)
+
If you are going to be pushing changesets directly,  
 +
* you will be cloning a [[team repository]] instead.
 +
* make sure you push to a https:// URL. Or you will get "<code>remote: ssl required</code>" errors.
-
NOTE: If you find that building after checkout fails while external binaries are being fetched and your Internet access requires a proxy server, you need to let Ant know about your proxy.  The easiest way to do this is via the <tt>ANT_OPTS</tt> environment variable. For example,
+
If you are having difficulty cloning the repository from this server, you may wish to try an unofficial mirror: https://bitbucket.org/netbeans/main-silver/
-
<pre>set ANT_OPTS="-Dhttp.proxyHost=proxy.mycompany.com -Dhttp.proxyPort=8080"</pre>
+
-
on MS Windows. Replace <tt>set</tt> with <tt>export</tt> to achieve the same result on Unix.
+
-
===Tracking broken builds===
+
=Tracking broken builds=
 +
At first, make sure your changes cannot cause harm to other developers - see the checklist how to avoid this - [[DevFaqCheckListBeforePush]]
If you push changes to the Mercurial server
If you push changes to the Mercurial server
Line 38: Line 43:
to let others know you are working on the problem.)
to let others know you are working on the problem.)
-
===Machine config===
+
=Machine config=
You'd be fine with any decent PC or laptop.
You'd be fine with any decent PC or laptop.
As usual more RAM, faster CPU are better than less RAM, slower CPU.
As usual more RAM, faster CPU are better than less RAM, slower CPU.
The source tree is big, so dial-up users may have difficulty getting it.
The source tree is big, so dial-up users may have difficulty getting it.
 +
 +
==Heap size==
You should increase the heap size for Ant, the default is not enough, e.g. by setting environment variable
You should increase the heap size for Ant, the default is not enough, e.g. by setting environment variable
-
<pre>
+
<source lang="bash">
-
export ANT_OPTS="-Xmx256m -XX:MaxPermSize=96m"
+
export ANT_OPTS="-Xmx1G"
-
</pre>
+
</source>
-
===Working with subsets of the source tree===
+
If you still experience a <code>java.lang.OutOfMemoryError: Java heap space</code> error during the build, further increase the heap size.
-
NetBeans IDE consists of [[NB6ModuleClusters| module clusters]]. A cluster is a collection of modules which together implement related
+
If you are building NetBeans 8.1 or older using JDK7 then provide also <tt>"-XX:MaxPermSize=512m"</tt> as ANT_OPTS variable. Complete ANT_OPTS variable should look like this for JDK7: <tt>export ANT_OPTS="-Xmx1G -XX:MaxPermSize=512m"</tt>
-
functionality. An old list is as follows:
+
-
* nb.cluster.nb, nb.cluster.platform, nb.cluster.ide, nb.cluster.xml, nb.cluster.java, nb.cluster.profiler, nb.cluster.apisupport, nb.cluster.harness, nb.cluster.j2ee, nb.cluster.visualweb, nb.cluster.uml, nb.cluster.mobility, nb.cluster.soa, nb.cluster.ruby
+
==Proxies==
-
'''Example: Ruby support only'''
+
If you find that building after checkout fails while [[ExternalBinaries]] are being fetched and your Internet access requires a proxy server, you need to let Ant know about your proxy.
-
Based on the cluster dependency matrix we know that we need
+
One way to do this is via the <tt>ANT_OPTS</tt> environment variable. For example,
 +
<pre>set ANT_OPTS="-Dhttp.proxyHost=proxy.mycompany.com -Dhttp.proxyPort=8080"</pre>
 +
on MS Windows.  Replace <tt>set</tt> with <tt>export</tt> to achieve the same result on Unix.
-
* nb.cluster.nb
+
Assuming your proxy is configured at the operating system level, an easier way is to add to ~/.antrc (Unix):
-
* nb.cluster.platform
+
-
* nb.cluster.ide
+
-
* nb.cluster.ruby
+
 +
<tt>ANT_ARGS='-autoproxy'</tt>
 +
 +
Windows would be similar. This style is convenient because each Ant invocation will pick up your _current_ proxy settings automatically.
 +
 +
If nothing above works it is probably that you are sitting behind a firewall that requires authentication. Unfortunately, it is currently not (longer?) possible to provide user and password proxy authentication parameters through system properties. The only option left is to modify the code of <tt>DownloadBinaries</tt>. Edit <tt>nbbuild/antsrc/org/netbeans/nbbuild/extlibs/DownloadBinaries.java</tt> and on after line 228 (<tt>for (String prefix : server.split(" "))</tt>) add the following lines:
<pre>
<pre>
-
mkdir nbsrc
+
  System.setProperty("http.proxyPort", "<port>");
-
cd nbsrc
+
  System.setProperty("http.proxyHost", "<your host>");
 +
  Authenticator.setDefault(new Authenticator() {
 +
      protected PasswordAuthentication getPasswordAuthentication() {
 +
        return new PasswordAuthentication("<domain>\\<user>","<password>".toCharArray());
 +
      }
 +
  });
 +
</pre>
-
# An example "well-known" cluster, if you wish to use a custom list of clusers, use nb.clusters.list rather than cluster.config.
+
Replace <your host>, <port>, <domain>, <user>, and <password> by your own values. Don't forget to add the missing imports:
-
echo cluster.config=ruby>> nbbuild/user.build.properties
+
-
ant -f nbbuild/build.xml
+
<pre>
-
ant -f nbbuild/build.xml tryme
+
import java.net.Authenticator;
-
ant -f nbbuild/build.xml clean
+
import java.net.PasswordAuthentication;
</pre>
</pre>
-
For the full list of cluster configurations see the file
+
Next time you clean or build, the file will be compiled
-
<tt>nbbuild/cluster.properties</tt>
+
-
in your checkout.
+
-
You can also have a custom list of clusters which doesn't correspond to any "well-known" cluster configuration.  For example
+
=Working with clusters=
-
if you work on the Ruby support in NetBeans you probably want this
+
 +
[[DevFaqWhatIsACluster|Additional information about clusters.]]
 +
 +
The NetBeans IDE consists of several module clusters.
 +
A cluster is a collection of modules which together implement related
 +
functionality, such as Java EE support.
 +
A cluster often corresponds to a "Category" in Plugin Manager.
 +
 +
Cluster configurations are sets of clusters which form a complete IDE.
 +
Clusters usually depend on other clusters, so a valid config must include dependencies.
 +
<tt>nbbuild/cluster.properties</tt> lists available clusters and configurations
 +
as well as some other metadata about clusters.
 +
 +
You can select a configuration to build with the <tt>cluster.config</tt> property either on the ANT command line or in <tt>user.build.properties</tt>.
 +
 +
To use <tt>user.build.properties</tt>
 +
to build only Java SE support, but not the clusters it depends on, the contents of the file would would assign only the value of <tt>java</tt> to <tt>cluster.config</tt>
 +
<pre>cluster.config=java</pre>
 +
. If <tt>user.build.properties</tt> is empty except for other values of <tt>cluster.config</tt> which are to be replaced, you can configure the cluster selection and build NetBeans by:
<pre>
<pre>
-
echo nb.clusters.list=nb.cluster.nb,nb.cluster.platform,nb.cluster.ide,nb.cluster.ruby,nb.cluster.java,nb.cluster.apisupport,nb.cluster.harness,nb.cluster.profiler>> nbbuild/user.build.properties
+
echo cluster.config=java > nbbuild/user.build.properties
 +
ant
</pre>
</pre>
-
to add NetBeans module development support, including the profiler, to the same build which you would use yourself.
+
ANT can de directed to build a single cluster at a time. Building <tt>java</tt> can be done by:
-
 
+
-
Do you want to build just a single cluster? For example, to build the <tt>visualweb</tt> cluster, run:
+
<pre>
<pre>
-
ant -Drebuild.cluster.name=nb.cluster.visualweb rebuild-cluster
+
ant -Dname=java rebuild-cluster
</pre>
</pre>
-
===Common Mistakes, Tips and Tricks===
+
=Common Mistakes, Tips and Tricks=
-
====Do not use JDK 6 to build!====
+
==Using the wrong JDK==
-
NetBeans build uses JDK 1.5.x and some code that compiles with JDK 6 will not compile with 1.5.x.
+
The current development sources requires JDK 8 to build.
-
(Check the '''Java Platform''' combo in the '''Libraries''' tab of one of your modules.
+
 
-
This controls <tt>nbjdk.home</tt> in <tt>nbbuild/user.build.properties</tt>. It must be set to a JDK 5 instance.)
+
* NetBeans 8.1 to NetBean 7.4 requires JDK7. You will be prevented from building using JDK 8, to prevent you from accidentally using 8+ APIs.
 +
* NetBeans 6.9 to NetBeans 7.3 require JDK 6 to build. You will be prevented from building using JDK 7, to prevent you from accidentally using 7+ APIs.
 +
* NetBeans 6.8 and older build with JDK 5 and similarly refuse by default to be built using JDK 6+.
 +
 
 +
Check the '''Java Platform''' combo in the '''Libraries''' tab of one of your modules.
 +
This controls <tt>nbjdk.home</tt> in <tt>nbbuild/user.build.properties</tt>.
Check this file to make sure it exists and have a line like this
Check this file to make sure it exists and have a line like this
<pre>
<pre>
-
nbjdk.home=/opt/jdk5
+
nbjdk.home=/opt/jdk8
</pre>
</pre>
Line 112: Line 146:
<pre>
<pre>
-
nbjdk.home=C:<br>Program Files<br>Java<br>jdk1.5.0_16
+
nbjdk.home=C:\\Program Files\\Java\\jdk1.8.0_66
</pre>
</pre>
Line 119: Line 153:
(Changes made from the IDE will always be stored in <tt>user.build.properties</tt>.)
(Changes made from the IDE will always be stored in <tt>user.build.properties</tt>.)
-
So long as <tt>nbjdk.home</tt> is configured, it is fine (and in fact encouraged)
+
So long as <tt>nbjdk.home</tt> is configured, it is fine
-
to use JDK 6 to actually run Ant,
+
to use a different JDK version to actually run Ant,
-
or equivalently to run Ant from inside the IDE running on JDK 6.
+
or equivalently to run Ant from inside the IDE running on a different JDK.
-
{{attachments|
+
For example, you can run NetBeans 7.0 on JDK 7,
-
* [[Media:TRAINING_JAVA_PROGRAMM_WorkingWithNetBeansSources.rtf]]}}
+
and build its own sources so long as <tt>nbjdk.home</tt> is set to JDK 6.
 +
Targets like <tt>ant tryme</tt> or <tt>ant -f some.module/build.xml run</tt> will use the configured JDK for the tested IDE instance.
 +
 
 +
==Try NetBeans build==
 +
It is possible to run just built NetBeans using temporary directories for user dir,... While in <tt>nbbuild</tt> directory type
 +
<source lang="bash">
 +
ant tryme
 +
</source>
 +
It creates <tt>User directory</tt> in <tt>.../nbbuild/testuserdir</tt>

Current revision as of 22:55, 11 July 2016

So you want to tinker with the code, build the whole IDE from sources, implement features yourself? This is the minimum to get you started.

If you are interested in sources for NetBeans 6.0 or earlier, see: WorkingWithNetBeansSourcesPre61

Contents

Tools

You need the following to be installed on your machine:

  • JDK 8
    • JDK 8 is required to build NetBeans sources after NetBeans 8.1
    • JDK 7 you can still use for compiling of sources NetBeans 8.1 to 7.4
    • JDK 6 you can still use for compiling of sources NetBeans 7.3 or older
  • Recent Apache Ant release (1.9.6 is current as of this writing)
  • Recent Mercurial release (3.6 is current as of this writing), presupposing Python 2.5.1 or later

Running ant at the root of the source tree should suffice to build the complete IDE. The whole source tree has NetBeans project metadata so you can just use NetBeans to develop NetBeans. For example, open any module project (top-level directory), make some edits, and click Run Project to try the IDE with your modifications.

Mercurial access

$ hg clone http://hg.netbeans.org/main-silver/

If you are going to be pushing changesets directly,

  • you will be cloning a team repository instead.
  • make sure you push to a https:// URL. Or you will get "remote: ssl required" errors.

If you are having difficulty cloning the repository from this server, you may wish to try an unofficial mirror: https://bitbucket.org/netbeans/main-silver/

Tracking broken builds

At first, make sure your changes cannot cause harm to other developers - see the checklist how to avoid this - DevFaqCheckListBeforePush

If you push changes to the Mercurial server you have to be subscribed to broken_builds@netbeans.org (send an empty message to broken_builds-subscribe@netbeans.org). Hudson, the continuous integration build machine, sends messages to this alias. Any build breakage must be dealt with immediately to avoid blocking others' work. (Reply to the alias as soon as you see that you are at fault to let others know you are working on the problem.)

Machine config

You'd be fine with any decent PC or laptop. As usual more RAM, faster CPU are better than less RAM, slower CPU. The source tree is big, so dial-up users may have difficulty getting it.

Heap size

You should increase the heap size for Ant, the default is not enough, e.g. by setting environment variable

export ANT_OPTS="-Xmx1G"

If you still experience a java.lang.OutOfMemoryError: Java heap space error during the build, further increase the heap size.

If you are building NetBeans 8.1 or older using JDK7 then provide also "-XX:MaxPermSize=512m" as ANT_OPTS variable. Complete ANT_OPTS variable should look like this for JDK7: export ANT_OPTS="-Xmx1G -XX:MaxPermSize=512m"

Proxies

If you find that building after checkout fails while ExternalBinaries are being fetched and your Internet access requires a proxy server, you need to let Ant know about your proxy.

One way to do this is via the ANT_OPTS environment variable. For example,

set ANT_OPTS="-Dhttp.proxyHost=proxy.mycompany.com -Dhttp.proxyPort=8080"

on MS Windows. Replace set with export to achieve the same result on Unix.

Assuming your proxy is configured at the operating system level, an easier way is to add to ~/.antrc (Unix):

ANT_ARGS='-autoproxy'

Windows would be similar. This style is convenient because each Ant invocation will pick up your _current_ proxy settings automatically.

If nothing above works it is probably that you are sitting behind a firewall that requires authentication. Unfortunately, it is currently not (longer?) possible to provide user and password proxy authentication parameters through system properties. The only option left is to modify the code of DownloadBinaries. Edit nbbuild/antsrc/org/netbeans/nbbuild/extlibs/DownloadBinaries.java and on after line 228 (for (String prefix : server.split(" "))) add the following lines:

   System.setProperty("http.proxyPort", "<port>");
   System.setProperty("http.proxyHost", "<your host>");
   Authenticator.setDefault(new Authenticator() {
      protected PasswordAuthentication getPasswordAuthentication() {
         return new PasswordAuthentication("<domain>\\<user>","<password>".toCharArray());
      }
   });

Replace <your host>, <port>, <domain>, <user>, and <password> by your own values. Don't forget to add the missing imports:

import java.net.Authenticator;
import java.net.PasswordAuthentication;

Next time you clean or build, the file will be compiled

Working with clusters

Additional information about clusters.

The NetBeans IDE consists of several module clusters. A cluster is a collection of modules which together implement related functionality, such as Java EE support. A cluster often corresponds to a "Category" in Plugin Manager.

Cluster configurations are sets of clusters which form a complete IDE. Clusters usually depend on other clusters, so a valid config must include dependencies. nbbuild/cluster.properties lists available clusters and configurations as well as some other metadata about clusters.

You can select a configuration to build with the cluster.config property either on the ANT command line or in user.build.properties.

To use user.build.properties to build only Java SE support, but not the clusters it depends on, the contents of the file would would assign only the value of java to cluster.config

cluster.config=java

. If user.build.properties is empty except for other values of cluster.config which are to be replaced, you can configure the cluster selection and build NetBeans by:

echo cluster.config=java > nbbuild/user.build.properties
ant

ANT can de directed to build a single cluster at a time. Building java can be done by:

ant -Dname=java rebuild-cluster

Common Mistakes, Tips and Tricks

Using the wrong JDK

The current development sources requires JDK 8 to build.

  • NetBeans 8.1 to NetBean 7.4 requires JDK7. You will be prevented from building using JDK 8, to prevent you from accidentally using 8+ APIs.
  • NetBeans 6.9 to NetBeans 7.3 require JDK 6 to build. You will be prevented from building using JDK 7, to prevent you from accidentally using 7+ APIs.
  • NetBeans 6.8 and older build with JDK 5 and similarly refuse by default to be built using JDK 6+.

Check the Java Platform combo in the Libraries tab of one of your modules. This controls nbjdk.home in nbbuild/user.build.properties. Check this file to make sure it exists and have a line like this

nbjdk.home=/opt/jdk8

On Windows, the file separator must be escaped since it is a metacharacter; e.g.

nbjdk.home=C:\\Program Files\\Java\\jdk1.8.0_66

You can also create ~/.nbbuild.properties for settings which should apply to any NB checkout on the machine unless overridden in user.build.properties. (Changes made from the IDE will always be stored in user.build.properties.)

So long as nbjdk.home is configured, it is fine to use a different JDK version to actually run Ant, or equivalently to run Ant from inside the IDE running on a different JDK. For example, you can run NetBeans 7.0 on JDK 7, and build its own sources so long as nbjdk.home is set to JDK 6. Targets like ant tryme or ant -f some.module/build.xml run will use the configured JDK for the tested IDE instance.

Try NetBeans build

It is possible to run just built NetBeans using temporary directories for user dir,... While in nbbuild directory type

ant tryme

It creates User directory in .../nbbuild/testuserdir

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo