I'm trying to generate the documentation, using javadoc, from one or two downloaded jar files (with the source of course, after having extracted everything).
But using javadoc, even in an Ant file, I'm being prevented from generating this because of silly things, specifically "package XXX does not exist" and "cannot find symbol"... I just want javadoc to put the text of these things (external references) in the html docs, but to document all the .java files it finds...
NB for anyone interested this is the download page with the download files (containing source) from which I'm trying to generate the API documentation: http://logback.qos.ch/download.html
Following Mark Rotteveel's help, my Ant build file now looks like this:
<?xml version="1.0" ?>
<project name="document logback core" default="doc">
<target name="doc">
<mkdir dir="javadoc" />
<property name="excludedPackages"
value="org.codehaus.*,javax.mail.*"/>
<javadoc destdir="javadoc" sourcepath="src" packagenames="main.*"
excludepackagenames="${excludedPackages}"
additionalparam="-Xdoclint:none" />
</target>
</project>
... but it still gives errors 1) about packages not being found, including "org.codehaus.[xxx...]" and "javax.mail.[xxx...]" and 2) about symbols not being found (although this may go away if I can solve the missing packages errors).
NB the build is said to be successful, but I get complaints about no source files being found (where there are indeed commented .java files), and no html at all is generated under \javadoc.
later, following Tony Pierce's success in generating these docs
Installed Ant 1.9.6, changed path accordingly, checked to make sure this was the version being used... tried again. Failed again. This was the end of my output:
[javadoc]
D:\Desktop\Downloads\logback-1.1.7.tar\logback-1.1.7\logback-core\src\test\java\ch\qos\logback\core\appender\ConsoleAppenderTest.java:32:
error: package org.junit does not exist [javadoc] import static
org.junit.Assert.assertEquals; [javadoc]_______________________^
[javadoc] javadoc: error - No public or protected classes found to
document. [javadoc] 1 error [javadoc] 100 warnings
BUILD SUCCESSFUL Total time: 2 seconds
It does create the javadoc folder... but this is empty.
NB about the above "package does not exist" error (there were many others): this one is particularly mystifying as I thought Ant somehow included junit by default (NB I am a complete newbie at Ant, just working through "Ant in Action").
But... with the Ant javac task you can set includeAntRuntime="true" ... according to this book that makes Ant's own junit.jar be included. Unfortunately the javadoc task doesn't support this attribute.
later still
My thinking was a bit muddled on this, to be honest: the simplest way I have found to compile javadocs from third-party source jars is just by extracting and then using the command line, typically:
javadoc -d docs -Xmaxwarns 10 -Xmaxerrs 10 -Xdoclint:none -sourcepath
. -subpackages ch.qos.logback.core
... as for javadoc for one's own code this doesn't seem to be a problem in Gradle (I was only glimpsing at Ant, aware that the future is Gradle... and it's not particularly difficult to get to grips with the basics).
NB If you install the Gradle STS plugin for Eclipse, and then create a new project using Gradle STS wizard your build file contains the line
apply plugin: 'eclipse'
... one of the effects of which is that by default the source as well as the executables for all your third-party dependencies will be downloaded under GRADLE_HOME during the build. Pretty good!
Java 8 introduced doclint which will treat certain problems as an error and not produce the documentation. It is possible to disable this by specifying the commandline option -Xdoclint:none.
See also: Turning off doclint in JDK 8 Javadoc
Eg in Ant you would need to do add a additionalparam="-Xdoclint:none" attribute to the javadoc task. A (slightly modified) example from Jaybird:
<target name="javadocs" depends="init,set-driver-sources">
<mkdir dir="${build.docs}"/>
<javadoc destdir="${build.docs}"
author="true"
version="true"
windowtitle="${Name} API"
doctitle="${Name}"
extdirs="${module.thirdparty}"
additionalparam="-Xdoclint:none"
excludepackagenames="${excludedPackages}"
bottom="Copyright © 2001-2015 Jaybird (Firebird JDBC/JCA) team. All rights reserved.">
<arg line="${java.module.arg}"/>
<classpath refid="javac.driver.classpath"/>
<sourcepath>
<pathelement path="${source.java}"/>
<pathelement path="${source.jna-client}"/>
</sourcepath>
<sourcepath refid="source.java.openoffice"/>
<sourcepath refid="source.java.additional"/>
<link href="http://docs.oracle.com/javase/7/docs/api/"/>
</javadoc>
</target>
Compile Errors With Custom Doclet with Java 9 or later
The -Xdoclint:none is an option of the standard doclet which will not work for custom doclets.
If you have a custom doclet and don't care about compilation errors, you can pass the --ignore-source-errors option either to the javadoc command line tool or to javax.tools.DocumentationTool.getTask(...) if you invoke your doclet programmatically.
The --ignore-source-errors option is not documented. Maybe because it might be removed in future. The clean way is to add all required libraries to the classpath (via the -classpath option to actually resolve the compilation errors).
I simplified your build file a bit and built the javadoc successfully. Here's what I did:
Downloaded the logback zip
Expanded the sources jars inside into a src directory
Ran ant 1.9.6 under java 8 with this:
<?xml version="1.0" ?>
<project name="document logback core" default="doc">
<target name="doc">
<mkdir dir="javadoc" />
<javadoc destdir="javadoc" sourcepath="src"
additionalparam="-Xdoclint:none" />
</target>
</project>
It produced a lot of warnings, but created a javadoc directory filled with html.
I removed excludepackagenames and dropped the packagenames element. In any case, packagenames="main.*" prevents the javadoc generation because the only root packages in the jar are ch and org.
Related
I have the pleasure of working on a embeded java program, which was writen 10+ years ago from a third party company. Source and project files were included.
It was imported into Eclipse and ported to a higher java version (17).
Now I'm stuck when trying to build the program. It uses ProGuard. The newest version was added to the project files. Config file proguard.pro was changed to discard rt.jar utilization in favore of the new methods. However, now I'm getting a error message:
BUILD FAILED
C:\mypath\build.xml:16: taskdef class proguard.ant.ProGuardTask cannot be found
using the classloader AntClassLoader[C:\mypath\obf\proguard.jar]
build.xml (original) is as follows:
<target name="obfuscate" description="obfuscate a jar file" depends="jar">
<taskdef name="proguard" classname="proguard.ant.ProGuardTask" classpath="obf/proguard.jar" />
<proguard configuration="obf/proguard.pro" />
</target>
The 'obf' folder is inside the project (sublevel of build.xml). File proguard.jar is inside of it. Anyone haveing any clues why would this error show? No other changes were made beside the listed ones.
So, it turned out that with new versions, the notation is not as it once was.
<taskdef resource="proguard/ant/task.properties" classpath="${proguard.path}/lib/proguard-ant.jar" />
I am generating Javadoc for my project and I want to link to the APIs of other projects that we use. I am doing the following: (I have tried with and without the packagelistURL and various versions of the API even though we are using 3.1)
<target name="javadoc" depends="initLocal">
<echo>Generating javadoc</echo>
<javadoc packagenames="*" sourcepath="${srcdir}" destdir="${docdir}" access="public" verbose="false">
<link offline="false" href="http://docs.oracle.com/javase/6/docs/api/" />
<link offline="false" href="http://commons.apache.org/proper/commons-lang/javadocs/api-3.1/" packagelistURL="http://commons.apache.org/proper/commons-lang/javadocs/api-3.1/package-list"/>
</javadoc>
</target>
I can see that it is successfully linking to the Java SE6 API but I can't seem to get it to use the commons-lang API. When I run the build I see the following:
[javadoc] C:\path\to\my\project\myClass.java:6: package org.apache.commons.lang3.builder does not exist
[javadoc] import org.apache.commons.lang3.builder.ReflectionToStringBuilder;
[javadoc] ^
[javadoc] C:\path\to\my\project\myClass.java:7: package org.apache.commons.lang3.builder does not exist
[javadoc] import org.apache.commons.lang3.builder.ToStringStyle;
Which seems a bit odd as the API link works and I can see both of those classes in the API. The project compiles correctly and the commons-lang jar is on the build path of the project.
Any ideas on what I am doing wrong here?
You've specified a link, but you haven't specified a classpath - you need to tell the javadoc task where to find the jar files (or whatever) which contain those types, just as you do when building. You should almost certainly use the same classpath for javadoc as you do for your javac task.
I receive the following warning:
[javac] build.xml:9: warning: 'includeantruntime' was not set,
defaulting to build.sysclasspath=last; set to false for repeatable builds
What does this mean?
Ant Runtime
Simply set includeantruntime="false":
<javac includeantruntime="false" ...>...</javac>
If you have to use the javac-task multiple times you might want to consider using PreSetDef to define your own javac-task that always sets includeantruntime="false".
Additional Details
From http://www.coderanch.com/t/503097/tools/warning-includeantruntime-was-not-set:
That's caused by a misfeature
introduced in Ant 1.8. Just add an
attribute of that name to the javac
task, set it to false, and forget it
ever happened.
From http://ant.apache.org/manual/Tasks/javac.html:
Whether to include the Ant run-time
libraries in the classpath; defaults
to yes, unless build.sysclasspath is
set. It is usually best to set this to
false so the script's behavior is not
sensitive to the environment in which
it is run.
As #Daniel Kutik mentioned, presetdef is a good option. Especially if one is working on a project with many build.xml files which one cannot, or prefers not to, edit (e.g., those from third-parties.)
To use presetdef, add these lines in your top-level build.xml file:
<presetdef name="javac">
<javac includeantruntime="false" />
</presetdef>
Now all subsequent javac tasks will essentially inherit includeantruntime="false". If your projects do actually need ant runtime libraries, you can either add them explicitly to your build files OR set includeantruntime="true". The latter will also get rid of warnings.
Subsequent javac tasks can still explicitly change this if desired, for example:
<javac destdir="out" includeantruntime="true">
<src path="foo.java" />
<src path="bar.java" />
</javac>
I'd recommend against using ANT_OPTS. It works, but it defeats the purpose of the warning. The warning tells one that one's build might behave differently on another system. Using ANT_OPTS makes this even more likely because now every system needs to use ANT_OPTS in the same way. Also, ANT_OPTS will apply globally, suppressing warnings willy-nilly in all your projects
Chet Hosey wrote a nice explanation here:
Historically, Ant always included its own runtime in the classpath made available to the javac task. So any libraries included with Ant, and any libraries available to ant, are automatically in your build's classpath whether you like it or not.
It was decided that this probably wasn't what most people wanted. So now there's an option for it.
If you choose "true" (for includeantruntime), then at least you know that your build classpath will include the Ant runtime. If you choose "false" then you are accepting the fact that the build behavior will change between older versions and 1.8+.
As annoyed as you are to see this warning, you'd be even less happy if your builds broke entirely. Keeping this default behavior allows unmodified build files to work consistently between versions of Ant.
The answer from Daniel works just perfect. Here is a sample snippet that I added to my build.xml:
<target name="compile">
<mkdir dir="${classes.dir}"/>
<javac srcdir="${src.dir}" destdir="${classes.dir}" includeantruntime="false">
<!-- ^^^^^^^^^^^^^^^^^^^^^^^^^ -->
<classpath>
<path id="application" location="${jar.dir}/${ant.project.name}.jar"/>
<path id="junit" location="${lib.dir}/junit-4.9b2.jar"/>
</classpath>
</javac>
</target>
If you like me work from commandline the quick answer is executing
export ANT_OPTS=-Dbuild.sysclasspath=ignore
And then run your ant script again.
Use <property name="build.sysclasspath" value="last"/> in your build.xml file
For more details search includeAntRuntime in Ant javac
Other possible values could be found here
i faced this same, i check in in program and feature. there was an update has install for jdk1.8 which is not compatible with my old setting(jdk1.6.0) for ant in eclipse.
I install that update.
right now, my ant project is build success.
Try it, hope this will be helpful.
I am trying to generate Javadoc html pages for my Android project in Eclipse. I have tried using the -linkoffline argument, as suggested here, as well as using the -classpath argument pointing to my android.jar file. Neither of these worked, as I still get package android.app does not exist (and other) warnings. I have also tried running the javadoc tool from the command line, rather than using Eclipse.
Ideally I would like to have my own generated pages for my classes, with all android.* and java.* classes linking to the online pages. I am using Mac OS 10.6 with Java version 1.6.0_20.
While trying to resolve a similar issue myself, the two main points I've found have been:
To include the android.jar file you're linking to within the classpath attribute of the javadoc Ant task. That means something like the following:
<javadoc ...
classpath="some/local/library.jar;
C:/Android/platforms/android-8/android.jar;
D:/another/library.jar" ... >
To add a link subitem under javadoc task in order to match the online Android Reference URL with a local copy of Android Reference package-list. That means something like the following:
<javadoc ...>
<link offline="true"
href="http://developer.android.com/reference/"
packagelistloc="C:/Android/docs/reference" />
</javadoc>
This was enough for me in order to show Android links within my project Javadoc.
Have you tried using an ant script for the javadocs? Name it javadoc.xml or something other than build.xml - else eclipse will pick it up as the default build script. Run the ant script either from inside eclipse (RMB on file | Run As | Ant Build), or from the console: ant -f <file-name.xml>.
Mine looks something similar to this:
<project basedir="." default="doc" name="metagloss api docs">
<property
name="android-sdk-docs"
value="/home/blackrax/opt/dev/android-sdk-linux_86/docs/reference"/>
<target name="doc" description="api docs - no piwik" depends="clean, delombok">
<javadoc destdir="docs">
<link offline="true"
href="http://d.android.com/reference"
packagelistLoc="${android-sdk-docs}" />
<fileset dir="src" includes="**/*.java" />
</javadoc>
</target>
<!-- more implementation, any remaining targets -->
</project>
Recently I started to use Eclipse's java compiler, because it is significantly faster than standard javac. I was told that it's faster because it performs incremental compiling. But I'm still a bit unsure about this since I can't find any authoritative documentation about both - eclispse's and sun's - compilers "incremental feature". Is it true that Sun's compiler always compiles every source file and Eclipse's compiler compile only changed files and those that are affected by such a change?
Edit: I'm not using Eclipse autobuild feature but instead I'm setting
-Dbuild.compiler=org.eclipse.jdt.core.JDTCompilerAdapter
for my ant builds.
Is it true that Sun's compiler always compiles every source file and Eclipse's compiler compile only changed files and those that are affected by such a change?
I believe that you are correct on both counts.
You can of course force Eclipse to recompile everything.
But the other part of the equation is that Java build tools like Ant and Maven are capable of only compiling classes that have changed, and their tree of dependent classes.
EDIT
In Ant, incremental compilation can be done in two ways:
By default the <javac> task compares the timestamps of .java and corresponding .class files, and only tells the Java compiler to recompile source (.java) files that are newer than their corresponding target (.class) files, or that don't have a target file at all.
The <depend> task also takes into account dependencies between classes, which it determines by reading and analysing the dependency information embedded in the .class files. Having determined which .class files are out of date, the <depend> task deletes them so a following <javac> task will recompile them. However, this is not entirely fool-proof. For example, extensive changes to the source code can lead to the <depend> task may be analysing stale dependencies. Also certain kinds of dependency (e.g. on static constants) are not apparent in the .class file format.
To understand why Ant <depend> is not fool-proof, read the "Limitations" section of the documentation.
Javac only compiles source files that are either named on the command line or are dependencies and are out of date. Eclipse may have a finer-grained way of deciding what that means.
Eclipse certainly does this. Also it does it at save time if you have that option turned on (and it is by default). It looks like sun also doesn't do this (it is very easy to test, just make a small project where A is the main class that uses class B, but B doesn't use class A. Then change A and compile the project again, see if the timestamp for b.class has changed.
This is the way many compilers work (also gcc for instance). You can use tools like ant and make to compile only the part the project that has changed. Also note that these tools aren't perfect, sometimes eclipse just loses track of the changes and you'll need to do a full rebuild.
Restating what I've heard here and phrasing it for lazy folks like me:
You can achieve incremental builds with the javac task in ant, but you should use the depend task to clear out .class files for your modified .java AND you must not leave the includes statement unspecified in the javac task. (Specifying just src path in the javac task and leaving includes unspecified causes javac recompile all sources it finds.)
Here are my depends and javac tasks. With the standard Oracle java compiler, only .java files I modify are compiled. Hope this helps!
<depend srcdir="JavaSource" destdir="${target.classes}" cache="${dependencies.dir}" closure="yes">
<classpath refid="compiler.classpath" />
<include name="**/*.java"/>
</depend>
<javac destdir="${target.classes}" debug="true" debuglevel="${debug.features}" optimize="${optimize.flag}" fork="yes" deprecation="no" source="1.6" target="1.6" encoding="UTF-8" includeantruntime="no">
<classpath refid="compiler.classpath"/>
<src path="JavaSource"/>
<include name="**/*.java" /> <!-- This enables the incremental build -->
</javac>