FaqCompileOnSave
How Compile on Save works
Contents |
Description
The Compile on Save (CoS) feature is designed to make 'save & compile & run' action faster. This can be helpful for users, which are used to run and test application immediately after making change is sources. It utilizes the .class files which are produced during updating the internal data about projects. These files are always up to date so there is no need to run ant to regenerate them again before each run, they are simply copied from the userdir to build/classes and the application is launched.
What is not Compile on Save
- The CoS is not related to the populating and updating informations about projects, which is indicated by 'Project scanning' label in the bottom right corner of main window. (this task was formerly named 'Compiling', which caused misunderstandings)
- The CoS in not related to error badges in project view and error highlighting in editor
- The CoS is not responsible for building .jar
How it works
The class files in userdir are always up to date (this is how java infrastructure works). On the first run the classes are copied to build folder and the application is launched with this folder on its classpath. After any further change&save in editor the class files are updated in both places - in userdir and build folder. This makes any further application run even faster, since the application is directly launched without copying anything (copying class files can take some time especially for large projects). The build folder is marked that it contains files produced by inner javac. The compile action is disabled since the sources are compiled automatically.
The classes produced by inner javac are not suitable to be put in jar, since it can contain code added by inner javac to recover from compilation errors. To build jar the ant is used as it was in previous version. At first the build dir must be cleared to avoid mixing the class produced by ant and inner javac. This clean must be called explicitly (see Action Summary). Then the sources are compiled to build dir and finally the jar is created from them. The compile action is enabled again. The save action does not change files in build folder until run action is called again to populate this folder by classes generated by inner javac.
Action Summary
Here is quick summary of what the actions exactly do:
- Run, Run file - The .class files are copied from userdir to build/classes if the build/class folder is empty or if it contains .class files produced by ant. The build/classes folder is added to classpath together with jars and other .class files the actual project depends on and the application is launched.
- Clean - The content of build/classes folder is deleted
- Clean & build - This action behaves like invoking Clean and Build, e.g. the output folder is cleared and the ant is called to produce .class files.
- Build - The build action works only when the build/classes are populated by classes produced by ant and created jar as expected. The user have to call clean first if the build dir contains classes produced by inner javac to avoid mixing the files in one jar. The warning popup will be shown in this case, to let used decide if he wants to call clean first or disable CoS.
- Compile - The compile action is only available if build dir contains classes produced by ant. Otherwise the compile has no sense, since the class files are compiled automatically.
Errors in sources
When developing application it is very common that the code is not compilable most of the time - some parts of code are not finished yet or are missing completely. Inner javac can recover from this state and can compile sources which are uncompilable by external javac. The code containing the error is simply replaced by code throwing RuntimeException. The IDE also shows warning when running project containing errors. The result of this approach is that the class produced by inner javac cannot be packed to output jar!
Need to compile badges
The Need to Compile badge (little wrench next to the node in project view) is shown whenever the .class file is not up to date - e.g. when the source file was changed after last compilation. If the build directory is populated by classes produced by inner javac (e.g. after run action) this case cannot happen - the compilation is always performed after the file was saved. If the build directory contains classes generated by ant (e.g after clean and build) the sources need to by compiled explicitly to get rid of this badge. The cause is described earlier - the class files in build dir are not updated on save in this case
External changes
After external changes is necessary to do clean&build so the changes are propagated correctly to java infrastructure!
Project dependency
When there are two project, one is depending on the other, the setting of the launched project is significant. When the main project (the depending projects) has Compile on Save on and it's launched the inner javac generates classes in all project the main is depending on (their settings are ignored). And vice versa when the main has compile on save off, the ant is used to compile all the project in dependency tree.
When CoS is not usable
The Compile on Save cannot be used in some specific cases. Here are the examples:
- The build.xml script contains additional actions added by user which are necessary for the run of the application - the compile on save does not use the ant to launch application so the additional task are not performed
- The important files in build/classes - The CoS in not usable when there is another task (another program, modified ant script) producing some files to build/classes, this folder is cleared before build - see the Action Summary
- Generating jar - it is better to turn CoS off when user want to build jar periodically and run application at the same time. When CoS is enabled the build/classes needs to be cleared before building jar so there is significant slowdown in the case.
How to turn it on/off
The Compile on Save is project specific option. It can be enabled/disabled in project properties, on Compilation tab. By default it is on for all new project created in 6.5. For project from previous versions the behavior is not changed (the CoS is disabled). When the CoS setting is changed the clean action is performed automatically to avoid mixing classes produced by various way.
Using Compile on Save in Maven Projects
In Maven projects, CoS is by default only turned on for tests. Go to the project properties dialog, Compile panel, to turn it on for main sources execution as well.
Resources (as defined in the pom) are not copied before Cos-enabled Run/Debug is performed, but immediately upon change. They are copied into the relevant output folder (target/classes for main sources and target/test-classes for test sources). TargetPath, Includes and Excludes of the resource definition are taken into account. Resources that shall be filtered are skipped. If you have changed such filtered resources, please perform 'mvn process-resources' resp 'mvn process-test-resources'
The .netbeans_automatic_build stamp file is placed into the relevant output folder to tell the IDE java infrastructure to start compiling and copying the class files there. The stamp file is created on project open and before executing any action in the IDE (with exception of Build project and Rebuild project). This should assure that while working with the project in the IDE, projects that have CoS enabled shall have the classes compiled and resources copied all the time.
\
This should cover, for example, the javarebel usecase and tapestry usecase when invoked via jetty:run goal invokation.
For web applications, resources are copied from the output folder to the expanded webapp and when using the IDE supported server deployment, the webapp gets redeployed eventually (based on the rules in the app server support codebase)
