| (NOTE: the following text is a vision for an Ant GUI by Stefan Vaillant |
| <mailto:Stephan.Vaillant@nokia.com> called Anttool. It is included here in the |
| Antidote docs section as it provides a better vision for what the GUI should be |
| than the current requirements document, and should be considered an integral |
| part of the long-term plans for Antidote. Simeon Fitch) |
| |
| |
| ----------------------------------------------------------------------- |
| |
| ******************** |
| **Anttool Proposal** |
| ******************** |
| |
| By: Stefan Vaillant <mailto:Stephan.Vaillant@nokia.com> |
| |
| ----------------------------------------------------------------------- |
| |
| Anttool Overview: |
| ----------------- |
| |
| With Anttool a user can manage the build process for existing ant build files. |
| By using the grafical user interface, the user can adjust certain properties to |
| his environment, start and cancel builds, monitor their progress and call |
| appropiate programs to fix problems. It is not possible to modify the build |
| file. Instead, an external XML editor or antidote should be used. |
| |
| |
| For inexperienced users, the tool provides an easy and efficient way to install |
| open source software: load software to the local system, build it and install |
| it. The tool can be used without any knowledge of XML or the ant DTD. Instead, |
| the user just adjusts the relevant properties to his environment and starts the |
| build. |
| |
| For programmers, the tool supports the basic build/test/edit cycle. Given an |
| existing ant build file, the programmer can use the grafical user interface to |
| execute individual targets, browse the effects of the build and start editors to |
| fix problems that occured during the build. |
| |
| |
| I general, anttool is ment for users who see the build file as a black-box: They |
| are not primarily interested in the internal structure of the build file nor in |
| modifiying it. Instead, they want to call ant with the appropiate arguments and |
| want to see, what is the result of the build. |
| |
| Therefore, anttool only shows targets and properties that are relevant for these |
| users. Tasks are not shown at all. |
| |
| |
| Anttool User Interface: |
| ----------------------- |
| |
| The user interface of anttool is devided into two panels: The "Control Panel" |
| shows all loaded build files and their targets. The "Project Panel" shows |
| details for one project, including the logging information from the last |
| build(s), the editable properties of an build and relevant files of that build. |
| |
| By default, the user interface does not show targets or properties that have no |
| description or a descriuption starting with a ".". These targets or properties |
| are called "hidden" in the following text. |
| |
| |
| The Control Panel: |
| ------------------ |
| |
| The Control Panel shows a tree with all loaded projects. For each project the |
| non-hidden targets are shown. (Anttool can be configured to show also hidden |
| targets, see Configuration below). |
| |
| If you move the cursor over a project or target, a description for it will be |
| shown as a tooltip. |
| |
| Two icons are prefixing the name of the project or target: one is visualizing |
| the state of the project or target, the other is a button to start or cancel the |
| project or target. The state icon can have the following different colors: |
| - green if the execution was successfull. |
| - yellow if an execution is needed because the output files are |
| out-of-date [not possible with current ant version?] |
| - red if the execution resulted in errors. |
| - white (i.e. nothing) if the state is unknown |
| [Alternative: what about buttons labeled with the target name? |
| The button is used for start/stopping the build. |
| No tree required then. ] |
| |
| |
| If you select a node in the tree, the Project Panel (see below) will show |
| details for the relevant project. |
| |
| If you right-click on a node in the tree, a pop-up menu will show the following |
| commands: |
| edit: open XML editor at selected element |
| open: in new window [? is that needed] |
| |
| |
| The Project Panel: |
| ------------------ |
| |
| The Project Panel consists of three tabs: |
| |
| The "Build Log" tab shows information about the last build(s), the "Properties" |
| tab shows non-hidden properties and the "Files" tab shows files relevant for the |
| project. |
| |
| The Build Log Tab: |
| |
| In this tab you can monitor the build on detail. A tree shows the executed |
| targets of a build, their tasks and log messages for each task. The start time |
| is noted after the build name. |
| |
| In the pop-up menu, you can choose from the following commands: |
| edit: open editor for shown file at shown location. |
| show log level->Error/Warning/Info/Verbose/Debug |
| (only the items possible are shown, |
| see configuration.) |
| |
| The Properties Tab: |
| |
| The properties tab shows all non-hidden properties of the project. (optionally, |
| also hidden properties can be shown, see Configuratin below.) |
| |
| Each Property is shown as follows: |
| <Name>: <entry field> <reset checkbox> |
| where |
| <Name> is name of the property, with "." and "-" replaced by " " |
| and first letters capatilized. |
| <entry field> is a text field to enter a value for the properts. |
| In some cases, special benas are shown: |
| Name ends with ".dir" => provide a file chooser to select a directory |
| Name ends with ".lib" => provide a file chooser to select .jar file |
| Name is "build.compiler" => provide combo box with possible compilers. |
| [selecting JDK's seems not well support in ant? |
| If you have e.g. JDK 1.2.1 and 1.2.2 installed, |
| how to easily select the compiler version?] |
| Name ends with ".jdk" => let the user select one of the configures |
| JDK's |
| [more general then build.compiler, but supported by ant?] |
| Name ends with ".file" => provide a file chooser |
| <reset checkbox> resets the value to the (default) value that is |
| contained in the .xml file |
| |
| All values entered are save in a file |
| $HOME/.ant/<full-path-build-file>.property. (See also Configuration.) |
| |
| If property values are changed, then ant is called with |
| main("-Dproperty1=value1 .."). |
| |
| [show also (class)pathes as property, use id instead of name? But: is that |
| required? Why not simply define individual properties for the required |
| libraries and combine them then to a path. ] |
| |
| |
| |
| The File Set Tab: |
| |
| This tab show files that are releated to the project. For each non-hidden |
| fileset of the project, the id of the fileset is shown and all files included to |
| that fileset. |
| |
| If you right-click on a file, a pop-up menu is shown with which you can start |
| programs to deal with these files. The relevant configuration information is |
| extracted from the existing operation system settings. |
| |
| [or: one tab for each fileset?] |
| |
| Repository: |
| ----------- |
| |
| [This needs some more work.] |
| |
| Anttool also simplyfies the loading of source files form the web. By using the |
| repository mechanism of anttool, you can perform the complete workflow from |
| download to install with just a few mouse clicks: |
| |
| select one out of the Repositories from the main menu. |
| Anttool will query the server for a list of up-to-date |
| packages. |
| |
| select one of the presented packages |
| Anttool will then download the selected package: |
| In case a .zip (or similar) package was selected, |
| the file is downloaded and |
| unpacked to "/Users/"<name>. |
| In case a CVS repository was selected, |
| the files are downloaded to "/Users/"<name>. |
| |
| Afterwards |
| a file with the name "build.xml" is searched |
| and loaded to anttool. |
| Optionally, the file "$HOME/.ant/default.properties" |
| is copied to "$HOME/.ant/<full-path-build-file>.properties, |
| overwriting the defaults in the downloaded build file |
| with your preferences (e.g. installation directory, JDK, ...) |
| [copy only relevant properties?] |
| |
| check if the properties in the selected project match your intention. |
| |
| press "start" on the project |
| |
| |
| Anttool Configuration: |
| ----------------------- |
| |
| The menu "Tools" in the menu bar allows you to adjust Anttool behavior to your |
| preferences and environment. |
| |
| The following menu entries are available: |
| |
| Configure JDKs: |
| Can be used to configure the JDKs available |
| on your system. The configured values are offered |
| for properties that end with ".jdk". |
| |
| The screen offers a table to edit a set of names |
| and pathes. |
| By pressing "rescan" the system is scanned for new JDKs |
| by consulting the installed software. |
| |
| [Should there be one combo box |
| Anttool JDK: <internal|JDK list|....> |
| that indicates the JDK that should be used to run ant? |
| Should that be even project specific setting? |
| ] |
| |
| Configure Repository: [better name?] |
| Anttool is aware of certain places where Anttool supporting software |
| can be found on the internet. |
| These URLs can be configured here. |
| These repositories are offered to the user when he selects |
| the "Repository" menu in the menu bar. |
| |
| The screen offers a table to edit a set of names |
| and URLs. |
| |
| Configure Libraries: |
| Can be used to configure the libraries available |
| on your system. The configured values are offered |
| for properties that end with ".lib". |
| |
| The screen offers a table to edit a set of names |
| and pathes. |
| By pressing "rescan" the system is scanned for new libraries |
| by searching below a directory. |
| |
| |
| Preferences: |
| show hidden targets: bool |
| [or: offer addition menu to start hidden targets?] |
| show hidden filesets: bool |
| show hidden properties: bool |
| |
| log level used for build: ... |
| number of log files saved: |
| number of log files shown in UI: |
| |
| Directory to save property values: |
| |
| file name remembered in file menu: |
| |
| checkig for new files in filesets: [seconds] |
| autoload new buildfile: [seconds, 0= never] |
| |
| |
| General features: |
| ----------------- |
| The menubar menu's are |
| File |
| Open... |
| Close |
| ------- |
| 1 buildfile.xml |
| 2 .... |
| 3 ... |
| ------ |
| Exit |
| Repository |
| Apache... as configured |
| <name2>... |
| .... |
| Options |
| Configure JDKs... |
| Configure Repository... |
| Configure Libraries... |
| Preferences... |
| Look&Feel... |
| Help |
| Antool Help... |
| Ant Web Home calls netscape |
| ----------- |
| About... |
| |
| |
| Build files can be dragged and dropped into anttool. |
| |
| The set off loaded build files should be saved on exit and |
| reloaded on restart automatically. |
| |
| |
| |
| Technical questions on the internals of anttool |
| ----------------------------------------------- |
| - How to detect if a target needs to be run (yellow color)? |
| Seems not be possible currently. |
| One solution [what will ant 2.0 contain?]: |
| Define new abstract class "MonitoredTask", inherited from Task. |
| Copy, Javac, javadoc, etc inherit from these. |
| MonitoredTask defines: |
| execute() { prepareTask(); if (executionNeeded) { perform() }; } |
| executionNeeded: boolean // signals that I need to run because output is |
| older than input |
| perform() |
| performMap() // what will happen with each file, i.e. |
| Main.java -> Main.class |
| UI.java -> UI.class |
| ... |
| or |
| Main.class -> lib.jar |
| UI.class -> lib.jar |
| size of Map should be equal to number of steps reported in loggin. |
| |
| Only "executionNeeded" is required to add a yellow flag for targets. The |
| performMap would be nice to have. It could be used later to show a finegrained |
| graph (or matrix) about what is happening during a build. |
| |
| Add configuration item on how often call the funtions (i.e. how often to do |
| the polling.) |
| |
| - How to do the calling of the external tools? |
| XML editor? (how to generate the dtd? How to execute "antstructure" |
| withour changing the build file.) |
| How to simulate the windows functionality for e.g. open java source with |
| JBuilder? |
| How to read the registry information? |
| How to do DDE calls? |
| |
| - is there any free installation tool for java? |
| (to install anttool itself) |