Changes between Version 77 and Version 78 of BuildSystem

12/15/12 22:37:35 (7 years ago)



  • BuildSystem

    v77 v78  
    1717 * UseCases 
     19== IDE integration 
     20 * [[UsingAsapRealizerInEclipse|Eclipse]] 
     21 * [[UsingTheBuildSystemInNetBeans|!NetBeans]] 
     22 * [[UsingTheBuildSystemInIntelliJ|!IntelliJ]] 
    2124=== How does it work? === 
    6164with the most recent release version. 
    63 === Using the build system in eclipse === 
    64 See UsingAsapRealizerInEclipse 
    66 === Using the build system in !NetBeans === 
    67 While it is possible to build the code of your project in !NetBeans, eclipse will currently give you a much smoother integration experience. Contributions towards automatically generating !NetBeans files from our build system are very welcome. Currently, !NetBeans projects have to be set up manually. 
    69 !NetBeans has, in the background, an ant based build system that is not unlike 
    70 our own build system. You can combine these, but you need to take some pre- 
    71 cautions when you create a !NetBeans project. Potential problem: by default, 
    72 !NetBeans want to create its own build.xml ant file in the project directory. 
    73 The solution is to first create a project, including the appropriate build file, and 
    74 the appropriate directory structure including the lib, the src, test\lib, and 
    75 test\src directories. Check that it compiles, etcetera, but after that: do an 
    76 ant clean. (Otherwise, !NetBeans will complain that there is already a build 
    77 directory in your project.) 
    79 Then there are basically two options to proceed: the first is to create a 
    80 !NetBeans "free form" project. In that case, !NetBeans will simply pick up your 
    81 existing build.xml file, and use that for it own builds. Disadvantage: it's ok 
    82 for basic editing, compiling, etcetera, but you cannot prot from all !NetBeans 
    83 features. The second option is to create a new !NetBeans "Java project from 
    84 existing sources". In that case, !NetBeans has its own build file, now called 
    85 nbbuild.xml. Advantage: you can profit from all !NetBeans features, and it 
    86 will not disturb the shared build files. Disadvantage: you must setup the 
    87 !NetBeans project carefully and manually update it for library changes, as we will describe now. 
    89 1. We assume that you are using !NetBeans 7.2 (or higher) 
    90 1. create, outside !NetBeans, a basic project in line with our build system. If you have an existing project, that's ok as well. Ensure that you have "resolved" the project dependencies, so that the contents of the lib and test\lib directories is what you need. (Use ant resolve)  
    91 1. Ensure that the your project has no build directory: for instance use ant clean. 
    92 1. Now create a new project within !NetBeans. Choose "New Java Project with Existing Sources". 
    93 1. Choose the correct project name (by default we pick the project directory name), and select the correct project folder. Enable the "Use dedicated Folder for Storing Libraries" option, but choose a different name than ".\lib". For instance, choose "nbproject\lib". !NetBeans stores some of its "own" info in its "lib" folder. Unfortunately, our version manager Ivy will discard such info from .\lib when you do an "ant resolve" operation, so we must give the !NetBeans lib a special place. 
    94 1. "Next", add the src folder to the list of "Source Package Folders", and add the test\src folder to "Test Package Folders". 
    95 1. "Now you can \Finish", and you have a !NetBeans project. Except that it won't compile, because you must correct the library settings: 
    96 1. The !NetBeans "Projects" panel on the left show two sets of libraries: "Libraries" and "Test Libraries" Right click on "Libraries" and choose "Add JAR/Folder". Navigate to the project's lib folder and add all jars that you find there. Also add the project's resource directory here. (This will ensure that this directory is on Java's classpath, so the "getResourceAsStream" method for loading resource data will work) Leave the "Reference as Relative Path" option enabled: this prevents !NetBeans from copying into its own nbproject\lib directory. Do the same with "Test Libraries", this time using the jars from test\lib, and the test\resource directory. As you can see we now have a junit-4.8.2.jar, that is present in our lib directory, but also two more !NetBeans "libraries", one for JUnit3.8.2 and one for JUnit4.8.2. The latter two should be removed.  
    97 1. By now, the project should be in shape: no unresolved libraries, it compiles and runs, and JUnits test work. 
    98 1. Note that whenever you change the contents of the lib directories, you will have to go back to the project properties page (from the File menu), and reestablish the correct libraries settings. For example, say you had some file "guava-r06.jar" inside your lib directory, but after the resolve operation it has been replaced by "guava-r07.jar" !NetBeans now automatically removes guava-r06.jar from its libraries, but does not auto-understand that it needs guava-r07.jar instead. Right-click on the !NetBeans project name, and choose "Resolve Reference Problems...". Select guava-r06.jar and click "Resolve". Now you can navigate to the project's lib directory, and select the new guava-r07.jar. For the time being, !NetBeans is now satisfied. In reality, it has not really removed the reference to guava-r06.jar, but it has added a redirection inside your own "private" !NetBeans settings. So next time that you resolve, it cannot find guava-r06.jar again. You can correct this by first removing the guava jar from the !NetBeans library, then adding the correct version. Problem: you cannot remove it while the reference problem is not solved. In the end, the easy solution is to first remove all jar files from lib (and also from test\lib if you expect changes over there) before the resolve, then add them back after the resolve. 
    101 ==== building jar files ==== 
    102 By default, compiled class files are included in the jar file produced by a build. But also all files inside the src directory, except for .java and 
    103 .form files are included. That is convenient if you want to include "resource" files, like data files, images , icons etcetera: put them in the 
    104 appropriate source directory, and use the Java getResourceAsStream() method for reading the data. Although this works, our strong preference 
    105 is to include \resources" into its own resource directory within your project. (Our ant build system puts your project's own resource directory on the classpath, as well as other directories that you specify in the file) !NetBeans auto-include of src documents is also not so nice if you have some secret-remarks.txt, or some huge remarks.doc word file in your source directories. In this case, you must set the files to exclude for packaging. For instance, via: Build | Set Main Project Configuration | Customize..., or via right-clicking the project tab, and selecting \Properties". Choose the \Packaging" tab, and to the "Exclude from jar file", for instance, add, **/*.txt, **/*.doc. 
    10766== More == 
    10867Detailed explanation of the build system is still being written. For specific questions, ask below.