Derby
  1. Derby
  2. DERBY-4841

Improve projecthelp for the top level Derby build script

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 10.7.1.1
    • Fix Version/s: 10.10.1.1
    • Component/s: Build tools
    • Labels:
      None

      Description

      Ant scripts are supposed to be self-describing. The following command is supposed to describe the public targets in the current directory:

      ant -projecthelp

      Here is the output of this command for the top level build script today:

      Main targets:

      checkCompilerLevel Make sure compiler level is Java 5 level or higher.
      class_size_catalog create the class size catalog – a java file
      createBranch Create a new branch (both docs and code)
      parsers Build the parsers
      release Build the release distributions
      setCompilerProperties Set the ant variables which identify the compiler classpaths. Remove the autosetProps logic when this target becomes mandatory.
      setInitialProperties Set the initial properties for this build script. This duplicates the property setting block in setCompilerProperties. Once we make setCompilerProperties mandatory, this target should be removed.
      state Build SanityState.java
      Default target: buildsource

      That does not seem like the list of public targets to me. This JIRA can be used as a place to anchor work which we do on improving the user documentation for our top level build script.

      I propose to make some changes to build.xml. Others are welcome to pile on. Here's how it works:

      1) The public targets are the ones which have "description" attributes.

      2) So to make a target public, fill in a "description" attribute for it.

      3) And to hide a target, move its "description" text into an introductory comment bracketed by "<!-" and "->"

        Issue Links

          Activity

          Hide
          Rick Hillegas added a comment -

          Attaching derby-4841-01-aa-ricksPicks.diff. This adjusts the public api exposed by "ant -projecthelp" for our top level build script. The new public api is simply my guess about what makes sense. Committed at subversion revision 1021827.

          After applying this patch, the output of "ant -projecthelp" is:

          Main targets:

          all Compile all of the source, including tests as well as production code.
          buildjars Build all of the Derby jar files.
          buildsource Compile the product source (does not build the tests).
          clobber Remove all build artifacts.
          createBranch Create a new branch (both docs and code).
          javadoc Build all of the javadoc, including the public api, the production javadoc, and the testing javadoc.
          junit-all Run the JUnit tests.
          junit-clean Remove the output produced by the JUnit tests.
          release Build the release distributions.
          Default target: buildsource

          Feel free to expose more targets if you think they are worth declaring in this top level project description.

          Touches the following file:

          M build.xml

          Show
          Rick Hillegas added a comment - Attaching derby-4841-01-aa-ricksPicks.diff. This adjusts the public api exposed by "ant -projecthelp" for our top level build script. The new public api is simply my guess about what makes sense. Committed at subversion revision 1021827. After applying this patch, the output of "ant -projecthelp" is: Main targets: all Compile all of the source, including tests as well as production code. buildjars Build all of the Derby jar files. buildsource Compile the product source (does not build the tests). clobber Remove all build artifacts. createBranch Create a new branch (both docs and code). javadoc Build all of the javadoc, including the public api, the production javadoc, and the testing javadoc. junit-all Run the JUnit tests. junit-clean Remove the output produced by the JUnit tests. release Build the release distributions. Default target: buildsource Feel free to expose more targets if you think they are worth declaring in this top level project description. Touches the following file: M build.xml
          Hide
          Dag H. Wanvik added a comment -

          Seems about right to me.
          In the past, I seem to remember there was some issue with running all three "clobber all buildjars" in one ant invocation. Is that safe to do now? "all" is also buggy, in that it doesn't always detect modified sources. Should such caveats be mentioned in this help, or is it sufficient to mention it in BUILDING.html?

          Show
          Dag H. Wanvik added a comment - Seems about right to me. In the past, I seem to remember there was some issue with running all three "clobber all buildjars" in one ant invocation. Is that safe to do now? "all" is also buggy, in that it doesn't always detect modified sources. Should such caveats be mentioned in this help, or is it sufficient to mention it in BUILDING.html?
          Hide
          Knut Anders Hatlen added a comment -

          > In the past, I seem to remember there was some issue with running
          > all three "clobber all buildjars" in one ant invocation. Is that
          > safe to do now?

          I'm not sure which issue you're referring to, but I have noticed that

          ant insane
          ant clobber all buildjars

          and

          ant insane
          ant clobber
          ant all buildjars

          behave differently. The first sequence of commands will result in a
          non-debug build, whereas the second sequence of commands will result
          in a debug build, even though they both invoke insane, clobber, all
          and buildjars in the same order.

          I don't know if it's a bug or intended behaviour, but if this is the
          issue you're referring to, it is still present on trunk.

          > "all" is also buggy, in that it doesn't always detect modified
          > sources. Should such caveats be mentioned in this help, or is it
          > sufficient to mention it in BUILDING.html?

          If there are problems with the dependency tracking in "all", it would
          be good to have those tracked in a JIRA issue. Incremental builds are
          still significantly faster than full builds, so I think it's important
          to have that working reliably.

          Show
          Knut Anders Hatlen added a comment - > In the past, I seem to remember there was some issue with running > all three "clobber all buildjars" in one ant invocation. Is that > safe to do now? I'm not sure which issue you're referring to, but I have noticed that ant insane ant clobber all buildjars and ant insane ant clobber ant all buildjars behave differently. The first sequence of commands will result in a non-debug build, whereas the second sequence of commands will result in a debug build, even though they both invoke insane, clobber, all and buildjars in the same order. I don't know if it's a bug or intended behaviour, but if this is the issue you're referring to, it is still present on trunk. > "all" is also buggy, in that it doesn't always detect modified > sources. Should such caveats be mentioned in this help, or is it > sufficient to mention it in BUILDING.html? If there are problems with the dependency tracking in "all", it would be good to have those tracked in a JIRA issue. Incremental builds are still significantly faster than full builds, so I think it's important to have that working reliably.
          Hide
          Rick Hillegas added a comment -

          Thanks for the additional analysis, Dag and Knut. Although ant lets you put multiple targets on the command line, the resulting behavior is not clear to me. For instance, ant handles property overrides in a very idiosyncratic way and off the top of my head I don't know how property overriding behaves when you put multiple targets on the command line. This is all I could find in the ant documentation (from the "Command Line" section of the ant manual):

          "It is also possible to specify one or more targets that should be executed. When omitted, the target that is specified in the default attribute of the project tag is used."

          From what you are saying, it seems that

          ant foo bar

          is not in general equivalent to

          ant foo
          ant bar

          Perhaps our documentation will be less brittle (and more accurate) if we always phrase it in terms of separate commands rather than composite ones. That, at least, is the approach taken in BUILDING.html.

          I have logged a new issue (DERBY-4845) to track the broken dependencies in our build scripts.

          Show
          Rick Hillegas added a comment - Thanks for the additional analysis, Dag and Knut. Although ant lets you put multiple targets on the command line, the resulting behavior is not clear to me. For instance, ant handles property overrides in a very idiosyncratic way and off the top of my head I don't know how property overriding behaves when you put multiple targets on the command line. This is all I could find in the ant documentation (from the "Command Line" section of the ant manual): "It is also possible to specify one or more targets that should be executed. When omitted, the target that is specified in the default attribute of the project tag is used." From what you are saying, it seems that ant foo bar is not in general equivalent to ant foo ant bar Perhaps our documentation will be less brittle (and more accurate) if we always phrase it in terms of separate commands rather than composite ones. That, at least, is the approach taken in BUILDING.html. I have logged a new issue ( DERBY-4845 ) to track the broken dependencies in our build scripts.
          Hide
          Rick Hillegas added a comment -

          I think that the work on this issue is done.

          Show
          Rick Hillegas added a comment - I think that the work on this issue is done.

            People

            • Assignee:
              Unassigned
              Reporter:
              Rick Hillegas
            • Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development