groovy-core/xdocs/faq.fml - groovy - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <faqs title="Frequently Asked Questions">

   <part id="general">
     <title>General</title>

     <faq id="whats-groovy">
       <question>
         What is Groovy?
       </question>
       <answer>
         <p>
           Groovy is a powerful high level language for the Java platform which compiles
           down to Java bytecode.
         </p>
         <p>
           Think of it as a Ruby or Python like language that is tightly integrated with
           the Java platform - allowing you the same powerful and concise coding syntax as
           Ruby or Pyton but allowing you to stay on the JVM and protect your investment in
           J2SE, J2EE and all the plethora of great useful Java code out there.
         </p>
       </answer>
     </faq>

     <faq id="why-groovy">
       <question>
         Why Groovy? Why don't you just use Jython, JRuby, bsh, rhino, pnuts, ...
       </question>
       <answer>
         <p>
           Firstly ports of existing languages like Python, Ruby, Smalltalk and JavaScript to the JVM
           are a good thing and we welcome them. If you already use and/or are fond of these languages
           please be our guests to use the Java-port of them.
         </p>
         <p>
           One of the main design goals of Groovy is to be a scripting language for Java developers to use.
           So we wanted to reuse both Java's semantics and the whole set of J2SE APIs rather than introduce
           a port of a different language with different semantics and APIs to learn and implement/maintain.
         </p>
         <p>
           e.g. in Groovy, java.lang.Object is the root of the object hierarchy,
           Object.equals(), Object.hashCode() and Comparable are used for comparions
           and lookups of objects, that java.util.List and java.util.Map are used for collections,
           Java Beans are fully supported and that Java and Groovy classes are interchangable
           inside the JVM.
           Groovy is built on top of the J2SE APIs, rather than having 2 parallel platforms etc.
         </p>
         <p>
           In other words we wanted the Groovy language to be very easy to pick up if you're already a Java developer
           and for there to be a very small number of new APIs to learn.
           By this statement we're not implying that Python / Ruby / JavaScript are hard to learn per se - its just
           there's more to know, things are more different and there's more APIs to learn.
         </p>
         <p>
           Think of Groovy as a Ruby or Python like language that is tightly integrated with
           the Java platform (as opposed to the Unix/Posix command shell and C-libraries)
           - allowing you the same powerful and concise coding syntax as
           Ruby or Pyton but allowing you to stay on the JVM and protect your investment in
           J2SE, J2EE and all the plethora of great useful Java code out there without any adapter layers or
           parallel API sets etc.
         </p>
         <p>
  	       There is a more detailed set of comparisions to other languages
     	    <a href="http://wiki.codehaus.org/groovy/ComparisonToOtherLanguages">here</a>
         </p>

       </answer>
     </faq>

     <faq id="dependencies">
       <question>
         What are the dependencies for Groovy?
       </question>
       <answer>
 		<p>As well as Java 1.4 and the Groovy jar we also depend at runtime on the ASM library</p>
       </answer>
     </faq>

     <faq id="licence">
       <question>
         What is the licence for Groovy?
       </question>
       <answer>
 		<p>Groovy is open source using a BSD / Apache style <a href="http://cvs.groovy.codehaus.org/viewcvs.cgi/groovy/groovy-core/LICENSE.txt?rev=HEAD&amp;view=auto">licence</a></p>
       </answer>
     </faq>

     <faq id="contribute">
       <question>
         How can I contribute to Groovy?
       </question>
       <answer>
         <p>
 		  There are many ways you can help and contribute to Groovy.
 		  Please read the <a href="contribute.html">contributing guide</a>
        </p>
       </answer>
     </faq>
   </part>

   <part id="using">
     <title>Using Groovy</title>

     <faq id="how-embed">
       <question>
         How can I embed Groovy into my Java application
       </question>
       <answer>
         <p>
 		  Please see this description of <a href="embedding.html">embedding Groovy</a>
        </p>
       </answer>
     </faq>

     <faq id="how-compile">
       <question>
         How can I compile Groovy to bytecode either at runtime or build time?
       </question>
       <answer>
         <p>
 		  Please see this description of <a href="compiling.html">compiling Groovy</a>
        </p>
       </answer>
     </faq>

     <faq id="how-run">
       <question>
         How can I run Groovy scripts?
       </question>
       <answer>
         <p>
 		  Please see this description of <a href="running.html">running Groovy code</a>
        </p>
       </answer>
     </faq>

     <faq id="problems">
       <question>
         I get errors when trying to run groovy, groovysh or groovyConsole. Whats wrong?
       </question>
       <answer>
         <p>
           Groovy depends on JDK 1.4 or later. Common errors people have when trying to run
           Groovy is that there's an old groovy jar on the CLASSPATH somewhere (have you
           checked in java/lib/ext?) or that JAVA_HOME points to an old JDK before JDK 1.4.x.
         </p>
         <p>
 		  For more help please see this description of <a href="running.html">running Groovy code</a>
        </p>
       </answer>
     </faq>

     <faq id="classpath">
       <question>
         How can I add stuff to the classpath when running things in groovysh or groovy?
       </question>
       <answer>
         <p>
           You can add things to your $CLASSPATH environment variable. Another popular option
           is to create a .groovy/lib directory in your home directory and add whatever jars you
           want to be available by default.
         </p>
         <p>
           e.g. if you wish to connect to your favourite JDBC database and do some scripting with it
           then add your JDBC driver to ~/.groovy/lib.
        </p>
       </answer>
     </faq>
   </part>


   <part id="language">
     <title>Questions about the Groovy language</title>

     <faq id="newline-before-brace">
       <question>
         Things work if I use Suns conventions and put { on the same line, but if I add a new line things break?
       </question>
       <answer>
         <p>
 		  When using closures with method calls we have some syntax sugar in Groovy which is sensitive to whitespace (newlines to be preceise).
 		  Please see this description in <a href="javadiff.html">common gotchas</a> for a full description
        </p>
       </answer>
     </faq>
   </part>

   <part id="gdk">
     <title>GDK (Groovy Development Kit)</title>

     <faq id="groovy-jgk">
       <question>
         What new methods are available on standard JDK classes?
       </question>
       <answer>
         <p>
 		  Please see this description of the <a href="groovy-jdk.html">Groovy JDK</a>
        </p>
       </answer>
     </faq>

     <faq id="what-closure">
       <question>
         What are Closures?
       </question>
       <answer>
         <p>
 		  Please see this description of <a href="closures.html">closures</a>
        </p>
       </answer>
     </faq>

     <faq id="operators">
       <question>
         How does operator overloading work?
       </question>
       <answer>
         <p>
 		  Please see this description of <a href="operators.html">operator overloading</a>
        </p>
       </answer>
     </faq>
   </part>


   <part id="developer">
     <title>Groovy Developers FAQ</title>

     <faq id="build">
       <question>
         How do I build Groovy from the source code?
       </question>
       <answer>
         <p>
         We use <a href="">Maven</a> as the build tool for Groovy.
         From a source distribution, or <a href="cvs-usage.html">CVS checkout</a>
         you need to install Maven as per the instructions on Maven's website.
         </p>
         <p>
         Basically this involves setting the JAVA_HOME and MAVEN_HOME environment
         variables and adding JAVA_HOME/bin and MAVEN_HOME/bin to your path.
         Once you have installed Maven you can build Groovy and run all the unit tests
         by typing the following in a command line shell
        </p>
 		<source>
 		maven
 		</source>
       </answer>
     </faq>

     <faq id="quick-build">
       <question>
         All the unit test cases take a while to run. Can I do a quicker build?
       </question>
       <answer>
         <p>
         You can do a full clean binary build without running the unit tests via..
        </p>
 		<source>
 		maven rebuild
 		</source>

         <p>
 		If you want to run all the unit test cases inside the same JVM, which saves quite a bit of time
 		although the output isn't as nice, you can use this command.
         </p>
 		<source>
 	    maven groovy:test-quick
 		</source>
       </answer>
     </faq>

     <faq id="some-tests">
       <question>
         All the unit test cases take a while to run. Can I run just some of the tests?
       </question>
       <answer>
         <p>
 		Or to run a specific test case you can do
         </p>
 		<source>
 		maven test:single -Dtestcase=CharsetToolkitTest
 		</source>

 		<p>
 		Where you pass in the name of a test case. If you want to run a single unit test case
 		written in Groovy in a slightly faster way you can try this...
 		</p>

 		<source>
 		maven groovy:test-single -Dtest=src/test/groovy/SomeTest.groovy
 		</source>

         <p>
 		or to run tests matching a certain pattern...
         </p>
 		<source>
 		maven test:match -Dtestmatch=Foo*Test.*
 		</source>

 		<p>
 		There is more details on unit testing groovy scripts <a href="unitTesting.html">here</a>
 		</p>
       </answer>
     </faq>
   </part>

 	<!-- More faqs or parts here -->
   <part id="committer">
     <title>Groovy Committers FAQ</title>

     <faq id="start">
       <question>
         I've just been given CVS commit access; what should I do now?
       </question>
       <answer>
         <p>
         If you've just been given CVS commit access see if you can do a commit.
         You'll need to do an SSH based CVS checkout. Once you've done this
         you should be able to edit the project.xml file and change yourself
         from being a committer to being a developer. Then try commit that
         and see if it works.
         If you need more help, please ask on IRC or email.
        </p>
       </answer>
     </faq>

     <faq id="rules">
       <question>
         What are the development rules?
       </question>
       <answer>
         <p>
         Please try and write unit test cases for all new features, patches or fixes.
        </p>
         <p>
         Its considered very bad form to commit code that doesn't compile or breaks the unit tests.
         We run a continuous integration build (using DamageControl) to ensure that the build in CVS
         works and the tests pass.
        </p>
         <p>
         Its useful to subscribe to all 3 mail lists, especially groovy-scm which shows all CVS commits
         along with any continuous integration build failures and JIRA issue changes.
        </p>
       </answer>
     </faq>

     <faq id="dc">
       <question>
         Where is the continuous integration build?
       </question>
       <answer>
         <p>
         We run DamageControl at codehaus. If a build fails a nag mail is sent to the groovy-scm mail list.
         You can watch DC do its stuff using your IRC client and joining
         <a href="irc://irc.codehaus.org/damagecontrol">#damagecontrol</a>.
        </p>
         <p>
         You can also view the latest DC <a href="http://builds.codehaus.org/log/groovy-core/">build logs</a>
         or see the <a href="http://builds.codehaus.org/checkout/groovy-core/target/test-reports/">test case results</a>
        </p>
       </answer>
     </faq>

     <faq id="cvs">
       <question>
         How do I use codehaus's CVS?
       </question>
       <answer>
         <p>
         Codehaus uses SSH for CVS access. So from the command line you'd type
         </p>
         <source>
 export CVS_RSH=ssh
 		</source>
 		<p>
 		Or if you're using eclipse you might find
 		<a href="http://www.jcraft.com/eclipse-cvsssh2/">this plugin</a>
 		handy.
 		I use it with extssh2 and it works great!
        </p>
       </answer>
     </faq>
   </part>

 </faqs>
	<?xml version="1.0" encoding="UTF-8"?>
	<faqs title="Frequently Asked Questions">

	<part id="general">
	<title>General</title>

	<faq id="whats-groovy">
	<question>
	What is Groovy?
	</question>
	<answer>
	<p>
	Groovy is a powerful high level language for the Java platform which compiles
	down to Java bytecode.
	</p>
	<p>
	Think of it as a Ruby or Python like language that is tightly integrated with
	the Java platform - allowing you the same powerful and concise coding syntax as
	Ruby or Pyton but allowing you to stay on the JVM and protect your investment in
	J2SE, J2EE and all the plethora of great useful Java code out there.
	</p>
	</answer>
	</faq>

	<faq id="why-groovy">
	<question>
	Why Groovy? Why don't you just use Jython, JRuby, bsh, rhino, pnuts, ...
	</question>
	<answer>
	<p>
	Firstly ports of existing languages like Python, Ruby, Smalltalk and JavaScript to the JVM
	are a good thing and we welcome them. If you already use and/or are fond of these languages
	please be our guests to use the Java-port of them.
	</p>
	<p>
	One of the main design goals of Groovy is to be a scripting language for Java developers to use.
	So we wanted to reuse both Java's semantics and the whole set of J2SE APIs rather than introduce
	a port of a different language with different semantics and APIs to learn and implement/maintain.
	</p>
	<p>
	e.g. in Groovy, java.lang.Object is the root of the object hierarchy,
	Object.equals(), Object.hashCode() and Comparable are used for comparions
	and lookups of objects, that java.util.List and java.util.Map are used for collections,
	Java Beans are fully supported and that Java and Groovy classes are interchangable
	inside the JVM.
	Groovy is built on top of the J2SE APIs, rather than having 2 parallel platforms etc.
	</p>
	<p>
	In other words we wanted the Groovy language to be very easy to pick up if you're already a Java developer
	and for there to be a very small number of new APIs to learn.
	By this statement we're not implying that Python / Ruby / JavaScript are hard to learn per se - its just
	there's more to know, things are more different and there's more APIs to learn.
	</p>
	<p>
	Think of Groovy as a Ruby or Python like language that is tightly integrated with
	the Java platform (as opposed to the Unix/Posix command shell and C-libraries)
	- allowing you the same powerful and concise coding syntax as
	Ruby or Pyton but allowing you to stay on the JVM and protect your investment in
	J2SE, J2EE and all the plethora of great useful Java code out there without any adapter layers or
	parallel API sets etc.
	</p>
	<p>
	There is a more detailed set of comparisions to other languages
	<a href="http://wiki.codehaus.org/groovy/ComparisonToOtherLanguages">here</a>
	</p>

	</answer>
	</faq>

	<faq id="dependencies">
	<question>
	What are the dependencies for Groovy?
	</question>
	<answer>
	<p>As well as Java 1.4 and the Groovy jar we also depend at runtime on the ASM library</p>
	</answer>
	</faq>

	<faq id="licence">
	<question>
	What is the licence for Groovy?
	</question>
	<answer>
	<p>Groovy is open source using a BSD / Apache style <a href="http://cvs.groovy.codehaus.org/viewcvs.cgi/groovy/groovy-core/LICENSE.txt?rev=HEAD&view=auto">licence</a></p>
	</answer>
	</faq>

	<faq id="contribute">
	<question>
	How can I contribute to Groovy?
	</question>
	<answer>
	<p>
	There are many ways you can help and contribute to Groovy.
	Please read the <a href="contribute.html">contributing guide</a>
	</p>
	</answer>
	</faq>
	</part>

	<part id="using">
	<title>Using Groovy</title>

	<faq id="how-embed">
	<question>
	How can I embed Groovy into my Java application
	</question>
	<answer>
	<p>
	Please see this description of <a href="embedding.html">embedding Groovy</a>
	</p>
	</answer>
	</faq>

	<faq id="how-compile">
	<question>
	How can I compile Groovy to bytecode either at runtime or build time?
	</question>
	<answer>
	<p>
	Please see this description of <a href="compiling.html">compiling Groovy</a>
	</p>
	</answer>
	</faq>

	<faq id="how-run">
	<question>
	How can I run Groovy scripts?
	</question>
	<answer>
	<p>
	Please see this description of <a href="running.html">running Groovy code</a>
	</p>
	</answer>
	</faq>

	<faq id="problems">
	<question>
	I get errors when trying to run groovy, groovysh or groovyConsole. Whats wrong?
	</question>
	<answer>
	<p>
	Groovy depends on JDK 1.4 or later. Common errors people have when trying to run
	Groovy is that there's an old groovy jar on the CLASSPATH somewhere (have you
	checked in java/lib/ext?) or that JAVA_HOME points to an old JDK before JDK 1.4.x.
	</p>
	<p>
	For more help please see this description of <a href="running.html">running Groovy code</a>
	</p>
	</answer>
	</faq>

	<faq id="classpath">
	<question>
	How can I add stuff to the classpath when running things in groovysh or groovy?
	</question>
	<answer>
	<p>
	You can add things to your $CLASSPATH environment variable. Another popular option
	is to create a .groovy/lib directory in your home directory and add whatever jars you
	want to be available by default.
	</p>
	<p>
	e.g. if you wish to connect to your favourite JDBC database and do some scripting with it
	then add your JDBC driver to ~/.groovy/lib.
	</p>
	</answer>
	</faq>
	</part>


	<part id="language">
	<title>Questions about the Groovy language</title>

	<faq id="newline-before-brace">
	<question>
	Things work if I use Suns conventions and put { on the same line, but if I add a new line things break?
	</question>
	<answer>
	<p>
	When using closures with method calls we have some syntax sugar in Groovy which is sensitive to whitespace (newlines to be preceise).
	Please see this description in <a href="javadiff.html">common gotchas</a> for a full description
	</p>
	</answer>
	</faq>
	</part>

	<part id="gdk">
	<title>GDK (Groovy Development Kit)</title>

	<faq id="groovy-jgk">
	<question>
	What new methods are available on standard JDK classes?
	</question>
	<answer>
	<p>
	Please see this description of the <a href="groovy-jdk.html">Groovy JDK</a>
	</p>
	</answer>
	</faq>

	<faq id="what-closure">
	<question>
	What are Closures?
	</question>
	<answer>
	<p>
	Please see this description of <a href="closures.html">closures</a>
	</p>
	</answer>
	</faq>

	<faq id="operators">
	<question>
	How does operator overloading work?
	</question>
	<answer>
	<p>
	Please see this description of <a href="operators.html">operator overloading</a>
	</p>
	</answer>
	</faq>
	</part>


	<part id="developer">
	<title>Groovy Developers FAQ</title>

	<faq id="build">
	<question>
	How do I build Groovy from the source code?
	</question>
	<answer>
	<p>
	We use <a href="">Maven</a> as the build tool for Groovy.
	From a source distribution, or <a href="cvs-usage.html">CVS checkout</a>
	you need to install Maven as per the instructions on Maven's website.
	</p>
	<p>
	Basically this involves setting the JAVA_HOME and MAVEN_HOME environment
	variables and adding JAVA_HOME/bin and MAVEN_HOME/bin to your path.
	Once you have installed Maven you can build Groovy and run all the unit tests
	by typing the following in a command line shell
	</p>
	<source>
	maven
	</source>
	</answer>
	</faq>

	<faq id="quick-build">
	<question>
	All the unit test cases take a while to run. Can I do a quicker build?
	</question>
	<answer>
	<p>
	You can do a full clean binary build without running the unit tests via..
	</p>
	<source>
	maven rebuild
	</source>

	<p>
	If you want to run all the unit test cases inside the same JVM, which saves quite a bit of time
	although the output isn't as nice, you can use this command.
	</p>
	<source>
	maven groovy:test-quick
	</source>
	</answer>
	</faq>

	<faq id="some-tests">
	<question>
	All the unit test cases take a while to run. Can I run just some of the tests?
	</question>
	<answer>
	<p>
	Or to run a specific test case you can do
	</p>
	<source>
	maven test:single -Dtestcase=CharsetToolkitTest
	</source>

	<p>
	Where you pass in the name of a test case. If you want to run a single unit test case
	written in Groovy in a slightly faster way you can try this...
	</p>

	<source>
	maven groovy:test-single -Dtest=src/test/groovy/SomeTest.groovy
	</source>

	<p>
	or to run tests matching a certain pattern...
	</p>
	<source>
	maven test:match -Dtestmatch=FooTest.
	</source>

	<p>
	There is more details on unit testing groovy scripts <a href="unitTesting.html">here</a>
	</p>
	</answer>
	</faq>
	</part>

	<!-- More faqs or parts here -->
	<part id="committer">
	<title>Groovy Committers FAQ</title>

	<faq id="start">
	<question>
	I've just been given CVS commit access; what should I do now?
	</question>
	<answer>
	<p>
	If you've just been given CVS commit access see if you can do a commit.
	You'll need to do an SSH based CVS checkout. Once you've done this
	you should be able to edit the project.xml file and change yourself
	from being a committer to being a developer. Then try commit that
	and see if it works.
	If you need more help, please ask on IRC or email.
	</p>
	</answer>
	</faq>

	<faq id="rules">
	<question>
	What are the development rules?
	</question>
	<answer>
	<p>
	Please try and write unit test cases for all new features, patches or fixes.
	</p>
	<p>
	Its considered very bad form to commit code that doesn't compile or breaks the unit tests.
	We run a continuous integration build (using DamageControl) to ensure that the build in CVS
	works and the tests pass.
	</p>
	<p>
	Its useful to subscribe to all 3 mail lists, especially groovy-scm which shows all CVS commits
	along with any continuous integration build failures and JIRA issue changes.
	</p>
	</answer>
	</faq>

	<faq id="dc">
	<question>
	Where is the continuous integration build?
	</question>
	<answer>
	<p>
	We run DamageControl at codehaus. If a build fails a nag mail is sent to the groovy-scm mail list.
	You can watch DC do its stuff using your IRC client and joining
	<a href="irc://irc.codehaus.org/damagecontrol">#damagecontrol</a>.
	</p>
	<p>
	You can also view the latest DC <a href="http://builds.codehaus.org/log/groovy-core/">build logs</a>
	or see the <a href="http://builds.codehaus.org/checkout/groovy-core/target/test-reports/">test case results</a>
	</p>
	</answer>
	</faq>

	<faq id="cvs">
	<question>
	How do I use codehaus's CVS?
	</question>
	<answer>
	<p>
	Codehaus uses SSH for CVS access. So from the command line you'd type
	</p>
	<source>
	export CVS_RSH=ssh
	</source>
	<p>
	Or if you're using eclipse you might find
	<a href="http://www.jcraft.com/eclipse-cvsssh2/">this plugin</a>
	handy.
	I use it with extssh2 and it works great!
	</p>
	</answer>
	</faq>
	</part>

	</faqs>