Gitiles
Code Review Sign In
source.supwisdom.com / portal_platform / tomcat-cms / 07b3087b89f4c23810bb2a7902fe5a06f392b984 / . / webapps / docs / building.html
blob: 5ee9662a8d32ac28f01e18a7518092932e4dd316 [file] [log] [blame]
Cheng Tang07b30872014-04-27 16:37:18 +0800[diff] [blame^]1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 7 (7.0.42) - Building Tomcat</title><meta name="author" content="Remy Maucherat, Tim Whittington"><style type="text/css" media="print">
2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4 </style><style type="text/css">
5 code {background-color:rgb(224,255,255);padding:0 0.1em;}
6 code.attributeName, code.propertyName {background-color:transparent;}
7 </style><style type="text/css">
8 .wrapped-source code { display: block; background-color: transparent; }
9 .wrapped-source div { margin: 0 0 0 1.25em; }
10 .wrapped-source p { margin: 0 0 0 1.25em; text-indent: -1.25em; }
11 </style><style type="text/css">
12 p.notice {
13 border: 1px solid rgb(255, 0, 0);
14 background-color: rgb(238, 238, 238);
15 color: rgb(0, 51, 102);
16 padding: 0.5em;
17 margin: 1em 2em 1em 1em;
18 }
19 </style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="./images/tomcat.gif" align="right" alt="
20 The Apache Tomcat Servlet/JSP Container
21 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.42, Jul 2 2013</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="./images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a href="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-hosting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li><li><a href="security-howto.html">28) Security Considerations</a></li><li><a href="windows-service-howto.html">29) Windows Service</a></li><li><a href="windows-auth-howto.html">30) Windows Authentication</a></li><li><a href="jdbc-pool.html">31) Tomcat's JDBC Pool</a></li><li><a href="web-socket-howto.html">32) WebSocket</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Tomcat Javadocs</a></li><li><a href="servletapi/index.html">Servlet Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.2 Javadocs</a></li><li><a href="elapi/index.html">EL 2.2 Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>Building Tomcat</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
22<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Download_a_Java_Development_Kit_(JDK)_version_6">Download a Java Development Kit (JDK) version 6</a></li><li><a href="#Install_Apache_Ant_1.8.1_or_later">Install Apache Ant 1.8.1 or later</a></li><li><a href="#Checkout_or_obtain_the_source_code_for_Tomcat_7.0">Checkout or obtain the source code for Tomcat 7.0</a></li><li><a href="#Building_Tomcat">Building Tomcat</a></li><li><a href="#Building_with_Eclipse">Building with Eclipse</a></li><li><a href="#Building_with_other_IDEs">Building with other IDEs</a></li></ul>
23</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
24
25<p>
26Building Apache Tomcat from source is very easy, and is the first step to contributing to
27Tomcat. The following is a step by step guide.
28</p>
29
30</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Download a Java Development Kit (JDK) version 6"><!--()--></a><a name="Download_a_Java_Development_Kit_(JDK)_version_6"><strong>Download a Java Development Kit (JDK) version 6</strong></a></font></td></tr><tr><td><blockquote>
31
32<p>
33Building Apache Tomcat requires a JDK (version 6) to be installed. You can download one from<br>
34<a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">http://www.oracle.com/technetwork/java/javase/downloads/index.html</a><br>
35or from another JDK vendor.
36</p>
37
38<p>
39<b>IMPORTANT</b>: Set an environment variable JAVA_HOME to the pathname of the
40directory into which you installed the JDK release.
41</p>
42
43</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Install Apache Ant 1.8.1 or later"><!--()--></a><a name="Install_Apache_Ant_1.8.1_or_later"><strong>Install Apache Ant 1.8.1 or later</strong></a></font></td></tr><tr><td><blockquote>
44
45<p>
46Download a binary distribution of Ant 1.8.1 or later from
47<a href="http://ant.apache.org/bindownload.cgi">here</a>.
48</p>
49
50<p>
51Unpack the binary distribution into a convenient location so that the
52Ant release resides in its own directory (conventionally named
53<code>apache-ant-1.8.x</code>). For the remainder of this guide,
54the symbolic name <code>${ant.home}</code> is used to refer to the full pathname of
55 the Ant installation directory directory.
56</p>
57
58<p>
59<b>IMPORTANT</b>: Create an ANT_HOME environment variable to point the directory <code>${ant.home}</code>,
60and modify the PATH environment variable to include directory
61<code>${ant.home}/bin</code> in its list. This makes the <code>ant</code> command line script
62available, which will be used to actually perform the build.
63</p>
64
65</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Checkout or obtain the source code for Tomcat 7.0"><!--()--></a><a name="Checkout_or_obtain_the_source_code_for_Tomcat_7.0"><strong>Checkout or obtain the source code for Tomcat 7.0</strong></a></font></td></tr><tr><td><blockquote>
66
67 <p>
68 Tomcat 7.0 SVN repository URL:
69 <a href="http://svn.apache.org/repos/asf/tomcat/tc7.0.x/trunk/">http://svn.apache.org/repos/asf/tomcat/tc7.0.x/trunk/</a>
70 </p>
71 <p>
72 Tomcat source packages:
73 <a href="http://tomcat.apache.org/download-70.cgi">http://tomcat.apache.org/download-70.cgi</a>.
74 </p>
75
76 <p>
77 Checkout the source using SVN, selecting a tag for released version or
78 trunk for the current development code, or download and unpack a
79 source package. For the remainder of this guide, the symbolic name
80 <code>${tomcat.source}</code> is used to refer to the
81 location where the source has been placed.
82 </p>
83
84</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Building Tomcat"><!--()--></a><a name="Building_Tomcat"><strong>Building Tomcat</strong></a></font></td></tr><tr><td><blockquote>
85
86<p>
87Use the following commands to build Tomcat:
88<br>
89<code><br>
90 cd ${tomcat.source}<br>
91 ant<br>
92</code>
93</p>
94
95<p>
96<b>WARNING:</b> Running this command will download libraries required
97 to build Tomcat to the <code>/usr/share/java</code> directory by default.
98 On a typical Linux or MacOX system, an ordinary user
99 will not have access to write to this directory, and, even if you do,
100 it is likely not appropriate for you to write there. On Windows
101 this usually corresponds to the <code>C:\usr\share\java</code> directory,
102 unless Cygwin is used. Read below to learn how to customize the directory
103 used to download the binaries.
104</p>
105
106<p>
107<b>NOTE:</b> Users accessing the Internet through a proxy must use a properties
108 file to indicate to Ant the proxy configuration. Read below for details.
109</p>
110
111<p>
112 The build can be controlled by creating a <code>${tomcat.source}/build.properties</code>
113 file and adding the following content to it:
114<br>
115<code><br>
116 # ----- Proxy setup -----<br>
117 # Uncomment if using a proxy server.<br>
118 #proxy.host=proxy.domain<br>
119 #proxy.port=8080<br>
120 #proxy.use=on<br>
121<br>
122 # ----- Default Base Path for Dependent Packages -----<br>
123 # Replace this path with the directory path where<br>
124 # dependencies binaries should be downloaded.<br>
125 base.path=/home/me/some-place-to-download-to<br>
126</code>
127</p>
128
129<p>
130Once the build has completed successfully, a usable Tomcat installation will have been
131produced in the <code>${tomcat.source}/output/build</code> directory, and can be started
132and stopped with the usual scripts.
133</p>
134</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Building with Eclipse"><!--()--></a><a name="Building_with_Eclipse"><strong>Building with Eclipse</strong></a></font></td></tr><tr><td><blockquote>
135
136<p>
137<b>IMPORTANT:</b> This is not a supported means of building Tomcat; this information is
138provided without warranty :-).
139The only supported means of building Tomcat is with the Ant build described above.
140However, some developers like to work on Java code with a Java IDE,
141and the following steps have been used by some developers.
142</p>
143
144<p>
145<b>NOTE:</b> This will not let you build everything under Eclipse;
146the build process requires use of Ant for the many stages that aren't
147simple Java compilations.
148However, it will allow you to view and edit the Java code,
149get warnings, reformat code, perform refactorings, run Tomcat
150under the IDE, and so on.
151</p>
152
153<p>
154<b>WARNING:</b> Do not forget to create and configure
155 <code>${tomcat.source}/build.properties</code> file as described above
156 before running any Ant targets.
157</p>
158
159<p>
160Sample Eclipse project files and launch targets are provided in the
161<code>res/ide-support/eclipse</code> directory of the source tree.
162The instructions below will automatically copy these into the required locations.
163</p>
164<p>
165An Ant target is provided as a convenience to download all binary dependencies, and to create
166the Eclipse project and classpath files in the root of the source tree.
167<br>
168<code><br>
169 cd ${tomcat.source}<br>
170 ant ide-eclipse<br>
171</code>
172</p>
173
174<p>
175Start Eclipse and create a new Workspace.
176</p>
177
178<p>
179Open the <em>Preferences</em> dialog and then select <em>Java-&gt;Build Path-&gt;Classpath
180Variables</em> to add two new <em>Classpath Variables</em>:
181</p>
182
183<p>
184<table border="1">
185 <tr><td>TOMCAT_LIBS_BASE</td><td>The same location as the <code>base.path</code>
186 setting in <code>build.properties</code>, where the binary dependencies have been downloaded</td></tr>
187 <tr><td>ANT_HOME</td><td>the base path of Ant 1.8.1 or later</td></tr>
188</table>
189</p>
190
191<p>
192Use <em>File-&gt;Import</em> and choose <em>Existing Projects into Workspace</em>.
193From there choose the root directory of the Tomcat source tree (<code>${tomcat.source}</code>)
194and import the Tomcat project located there.
195</p>
196
197<p>
198<code>start-tomcat</code> and <code>stop-tomcat</code> launch configurations are provided in
199<code>res/ide-support/eclipse</code> and will be available in the <em>Run-&gt;Run Configurations</em>
200dialog. Use these to start and stop Tomcat from Eclipse.
201<br>If you want to configure these yourself (or are using a different IDE)
202then use <code>org.apache.catalina.startup.Bootstrap</code> as the main class,
203<code>start</code>/<code>stop</code> etc. as program arguments, and specify <code>-Dcatalina.home=...</code>
204(with the name of your build directory) as VM arguments.
205</p>
206
207<p>
208Tweaking a few formatting preferences will make it much easier to keep consistent with Tomcat
209coding conventions (and have your contributions accepted):
210</p>
211<p>
212<table border="1">
213 <tr><td>Java -&gt; Code Style -&gt; Formatter -&gt; Edit...</td>
214 <td>Tab policy: Spaces only<br>Tab and Indentation size: 4</td></tr>
215 <tr><td>General -&gt; Editors -&gt; Text Editors</td>
216 <td>Displayed tab width: 2<br>Insert spaces for tabs<br>Show whitespace characters (optional)</td></tr>
217 <tr><td>XML -&gt; XML Files -&gt; Editor</td><td>Indent using spaces<br>Indentation size: 2</td></tr>
218 <tr><td>Ant -&gt; Editor -&gt; Formatter</td><td>Tab size: 2<br>Use tab character instead of spaces: unchecked</td></tr>
219</table>
220</p>
221
222</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Building with other IDEs"><!--()--></a><a name="Building_with_other_IDEs"><strong>Building with other IDEs</strong></a></font></td></tr><tr><td><blockquote>
223<p>
224The same general approach should work for most IDEs; it has been reported
225to work in IntelliJ IDEA, for example.
226</p>
227
228</blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
229 on improving documentation for Apache Tomcat.<br><br>
230 If you have trouble and need help, read
231 <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
232 and ask your question on the tomcat-users
233 <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
234 Do not ask such questions here. This is not a Q&amp;A section.<br><br>
235 The Apache Comments System is explained <a href="/tomcat-7.0-doc/comments.html">here</a>.
236 Comments may be removed by our moderators if they are either
237 implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
238 var comments_shortname = 'tomcat';
239 var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/building.html';
240 (function(w, d) {
241 if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
242 d.write('<div id="comments_thread"><\/div>');
243 var s = d.createElement('script');
244 s.type = 'text/javascript';
245 s.async = true;
246 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
247 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
248 }
249 else {
250 d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
251 }
252 })(window, document);
253 //--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
254 Copyright &copy; 1999-2013, Apache Software Foundation
255 </em></font></div></td></tr></table></body></html>