Quantcast

On Behalf of Cedric Beust: Documentation Woes

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

On Behalf of Cedric Beust: Documentation Woes

hans_d
Administrator
Cedric had some issues with out mailing list,  so I'm posting this on his behalf:

------------------
Hello Gradle users,

As some of you know, I recently tried to convert my build (http://testng.org) to Gradle but I didn't make much progress after a few hours, despite reading all the docs and mailing-list messages I could find, so I thought I'd share my experience here.

First of all, I have to say that I'm very impressed with the effort that went into the user guide.  The doc looks very professional and thorough, and I especially like the "one big web page" format (I did the exact same thing with TestNG and users absolutely love the fact they can do a search in the entire documentation so quickly or that they can print it and take it home with them).

Having said that, I think this particular document is not a good introduction for a couple of reasons:

    * It doesn't emphasize migration.  I'm guessing most people who will come across this document will want to convert an existing build (most likely ant and sometimes Maven) to Gradle.  This should be the first chapter.
    * It's not high level enough.  I've read the whole document maybe one and half times now and I'm still not sure what the concepts and building blocks are, what the difference between a module an a dependency is, what names are reserved, which ones are examples, etc...  I don't want to migrate my build by doing copy/pastes that I don't understand, because this guarantees that in a few months from now, I still won't understand how my build works, much less how to modify it.  I will only switch to a new build system if I can completely understand how it works, philosophically and technically.

TestNG's build is pretty straightforward (although interestingly, Maven can't achieve it, I can go into details if you're curious) and the two things that I needed to get started are:

    * How do I change the default source directories?
    * How do I configure my classpath to point to local jar files?

I ended up reading about variables called srcDirNames or something such, none of which are mentioned in that doc anywhere.  I still wasn't able to get these variables to work properly, by the way, so I'm still in the dark as to how to do this.  And I still don't know how to add local jar files to my compile and runtime classpath.  I'm guessing this involves specifying artifacts with some file:/// tricks or something like that, but I couldn't find any example anywhere (not just in your doc, I really mean anywhere in my web searches).

My ant build has been working flawlessly for years and I'm very happy with it but I'm also always trying to streamline things and I think Gradle has the power to trim down my build files considerably, so I'd really like to get this working and see if I would be happy with the final result.

Thanks for reading :-)

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: On Behalf of Cedric Beust: Documentation Woes

hans_d
Administrator
Hi Cedric,

On Mon, Dec 7, 2009 at 11:24 AM, Hans Dockter <[hidden email]> wrote:
Cedric had some issues with out mailing list,  so I'm posting this on his behalf:

------------------
Hello Gradle users,

As some of you know, I recently tried to convert my build (http://testng.org) to Gradle but I didn't make much progress after a few hours, despite reading all the docs and mailing-list messages I could find, so I thought I'd share my experience here.

First of all, I have to say that I'm very impressed with the effort that went into the user guide.  The doc looks very professional and thorough, and I especially like the "one big web page" format (I did the exact same thing with TestNG and users absolutely love the fact they can do a search in the entire documentation so quickly or that they can print it and take it home with them).

Having said that, I think this particular document is not a good introduction for a couple of reasons:

    * It doesn't emphasize migration.  I'm guessing most people who will come across this document will want to convert an existing build (most likely ant and sometimes Maven) to Gradle.  This should be the first chapter.

This is an important point we need to address.
 
    * It's not high level enough.  I've read the whole document maybe one and half times now and I'm still not sure what the concepts and building blocks are, what the difference between a module an a dependency is, what names are reserved, which ones are examples, etc...  I don't want to migrate my build by doing copy/pastes that I don't understand, because this guarantees that in a few months from now, I still won't understand how my build works, much less how to modify it.  I will only switch to a new build system if I can completely understand how it works, philosophically and technically.

Again I completely see your point. In particular regarding the philosophy. A high level article of the Gradle concepts and philosophy (together with examples) is work in progress. 
 

TestNG's build is pretty straightforward (although interestingly, Maven can't achieve it, I can go into details if you're curious) and the two things that I needed to get started are:

    * How do I change the default source directories?

I guess the best example would be to use your testng layout. Adam or me will post this sometimes today.
 
    * How do I configure my classpath to point to local jar files?

compile files('somepath_absolute_or_relative_to_project_root')
compile files(fileTree('lib').matching { include '**/*.jar', '**.*.zip' }
 

I ended up reading about variables called srcDirNames or something such, none of which are mentioned in that doc anywhere.  I still wasn't able to get these variables to work properly, by the way, so I'm still in the dark as to how to do this.  And I still don't know how to add local jar files to my compile and runtime classpath.  I'm guessing this involves specifying artifacts with some file:/// tricks or something like that, but I couldn't find any example anywhere (not just in your doc, I really mean anywhere in my web searches).

My ant build has been working flawlessly for years and I'm very happy with it but I'm also always trying to streamline things and I think Gradle has the power to trim down my build files considerably, so I'd really like to get this working and see if I would be happy with the final result.

I agree, your ant build is well in shape. But you will see just with the upcoming source layout example that the Gradle build is more concise and expressive about your project structure. The incremental build feature is also a very nice to get used to (trunk feature). There is a lot of other stuff. Concurrent unit test execution is probably nothing you are in need of ;).
BTW: Could you use the new TestNG scheduling engine also for running junit tests?

Cheers,

Hans
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: On Behalf of Cedric Beust: Documentation Woes

hans_d
Administrator
In reply to this post by hans_d
Hi Cedric,

On Mon, Dec 7, 2009 at 11:24 AM, Hans Dockter <[hidden email]> wrote:
Cedric had some issues with out mailing list,  so I'm posting this on his behalf:

------------------
Hello Gradle users,

As some of you know, I recently tried to convert my build (http://testng.org) to Gradle but I didn't make much progress after a few hours, despite reading all the docs and mailing-list messages I could find, so I thought I'd share my experience here.

First of all, I have to say that I'm very impressed with the effort that went into the user guide.  The doc looks very professional and thorough, and I especially like the "one big web page" format (I did the exact same thing with TestNG and users absolutely love the fact they can do a search in the entire documentation so quickly or that they can print it and take it home with them).

Having said that, I think this particular document is not a good introduction for a couple of reasons:

    * It doesn't emphasize migration.  I'm guessing most people who will come across this document will want to convert an existing build (most likely ant and sometimes Maven) to Gradle.  This should be the first chapter.
    * It's not high level enough.  I've read the whole document maybe one and half times now and I'm still not sure what the concepts and building blocks are, what the difference between a module an a dependency is, what names are reserved, which ones are examples, etc...  I don't want to migrate my build by doing copy/pastes that I don't understand, because this guarantees that in a few months from now, I still won't understand how my build works, much less how to modify it.  I will only switch to a new build system if I can completely understand how it works, philosophically and technically.

TestNG's build is pretty straightforward (although interestingly, Maven can't achieve it, I can go into details if you're curious)

I am curious.
 
and the two things that I needed to get started are:

    * How do I change the default source directories?

For testng you can do something like:

configurations {
   compile14
   compile.extendsFrom compile14
   runtime14.extendsFrom compile14
   runtime.extendsFrom runtime14
}

dependencies {
    compile files(fileTree(thirdPartyRoot).matching { include 'junit.jar', qdox, beanshellJar })
    compile15 files("$thirdPartyRoot/concurrent.jar")
}

sourceSets {
    jdk14 {
        java.srcDirs = ['src/main', 'src/jdk14']
        classesDir = "$buildDir/jdk14"
        compileClasspath = configurations.compile14
        runtimeClasspath = configurations.compile14
    }
    main {
        java.srcDirs = ['src/main', 'src/jdk15']
        classesDir = "$buildDir/jdk15"
    }
}

resourcesSpec = copySpec {
    from 'src/main/testng-1.0.dtd', 'src/testngtasks'
    from('resources') {
        exclude "**/.*", "**/CVS/*"
    }
}

processJdk14Resources {
    from resourcesSpec
}

processResources {
    from resourcesSpec // this automatically used the classesDir as target
}

sourceCompatibility = '1.5'
targetCompatibility = '1.5'

compileJdk14Java {
    targetCompatibility = '1.4'
}

Every sourceset creates automatically a process resources task, a compile task and a classes (combines compile and resources) task for its sources. Some configuration is done on the source set level and then delegated to the task, other configurations you need to apply directly against the tasks.

With the above you could execute:

gradle compileJdk14Java or gradle classes

The above is not as nice as it should be. The resources content is usually defined on the source set level but you can't properly share common set up yet. The source sets should be also aware of compatibility. There will be always properties where you need to go to the task but especially the properties that possibly span across tasks should be available in the source set. Another issue we will fix soon is that the JavaPlugin is doing a bit to much. For projects like yours it doesn't make sense to define a default sourceset and a default jar. The same is true for the Grails build for example which we are also porting to Gradle at the moment. We need to split the Java plugin in more pieces. In your case you we use the main source set for the 15 stuff in the real example above, but this is possibly not as expressive as it should be. Alternatively you could define a new 15 source set and the main source tasks just won't be used (and clutter the gradle -t output). This splitting apart is something we need to anyhow for another project next week.  What will be possible with 0.9 is:

sourceSets {
    jdk14 {
        java.srcDirs = ['src/main', 'src/jdk14']
        classesDir = "$buildDir/jdk14"
        resources {
            from resourcesSpec // this automatically used the classesDir as target
        }
        targetCompatibility = 'jsr14'
        compileClasspath = configurations.compile14
        runtimeClasspath = configurations.compile14
    }
    jdk15 {
        java.srcDirs = ['src/main', 'src/jdk15']
        classesDir = "$buildDir/jdk15"
        compileClasspath = configurations.compile15
        runtimeClasspath = configurations.compile15
        resources {
            from resourcesSpec // this automatically used the classesDir as target
        }
    }
}

So the last bit is I think a very nice looking piece where you define the what in a concise way and Gradle figures out the how. The idea of Gradle is to be declarative without being rigid. We don't see Gradle as a framework. Instead it provides a declarative extensible language to describe the 'what' of your build. The 'real' snippet is I think still better than the Ant script but unfortunately not as convincing. By the way, the real snippet also need a snapshot from trunk (as we use copySpecs in there). For how to download one, see: http://gradle.org/downloads.html

We don't have the concepts of test source sets yet. You would define a normal source set for your tests and then explicitly define your tests:

task jdk14Test(type: AntTest) {
    testClassesDir = sourceSets.integrationTest.classesDir // this is the dir we check for executable tests
    classpath = sourceSets.jdk14Tests.runtimeClasspath // this automatically creates the right dependencies on the test task to the classes task. We call this autowiring
}

To define a jar with the compiled classes you can do:

task jdk14Jar(type: Jar) << {
   from sourceSets.jdk14.classes
}

To do javadoc:

task jdk14Javadoc(type: Javadoc) {
   from(sourceSets.jdk14.allJava) {
      include 'my/public/api/**.java'
   } 
}

You could argue that the javadoc should be already provided by the source set. But this is not needed by all source sets. In the future we might have different source set types. 

I hope this helps. Please don't hesitate to ask any further questions. We are very happy to help in any way we can to make this a successful experiment :)

Cheers,

- Hans

--
Hans Dockter
Gradle Project Manager
 
    * How do I configure my classpath to point to local jar files?

I ended up reading about variables called srcDirNames or something such, none of which are mentioned in that doc anywhere.  I still wasn't able to get these variables to work properly, by the way, so I'm still in the dark as to how to do this.  And I still don't know how to add local jar files to my compile and runtime classpath.  I'm guessing this involves specifying artifacts with some file:/// tricks or something like that, but I couldn't find any example anywhere (not just in your doc, I really mean anywhere in my web searches).

My ant build has been working flawlessly for years and I'm very happy with it but I'm also always trying to streamline things and I think Gradle has the power to trim down my build files considerably, so I'd really like to get this working and see if I would be happy with the final result.

Thanks for reading :-)


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: On Behalf of Cedric Beust: Documentation Woes

Cedric Beust
Thanks for taking the time to do this, Hans.  I'm going to need some time to digest it :-)

--
Cedric
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: On Behalf of Cedric Beust: Documentation Woes

Adam Murdoch-2
In reply to this post by hans_d


On 8/12/09 4:24 AM, Hans Dockter wrote:

> Cedric had some issues with out mailing list,  so I'm posting this on
> his behalf:
>
> ------------------
> Hello Gradle users,
>
> As some of you know, I recently tried to convert my build
> (http://testng.org) to Gradle but I didn't make much progress after a
> few hours, despite reading all the docs and mailing-list messages I
> could find, so I thought I'd share my experience here.
>
> First of all, I have to say that I'm very impressed with the effort
> that went into the user guide.  The doc looks very professional and
> thorough, and I especially like the "one big web page" format (I did
> the exact same thing with TestNG and users absolutely love the fact
> they can do a search in the entire documentation so quickly or that
> they can print it and take it home with them).
>
> Having said that, I think this particular document is not a good
> introduction for a couple of reasons:
>
>     * It doesn't emphasize migration.  I'm guessing most people who
> will come across this document will want to convert an existing build
> (most likely ant and sometimes Maven) to Gradle.  This should be the
> first chapter.
>     * It's not high level enough.  I've read the whole document maybe
> one and half times now and I'm still not sure what the concepts and
> building blocks are, what the difference between a module an a
> dependency is, what names are reserved, which ones are examples, etc...

What's a good option for structuring this? I can think of a few
possibilities:
1. A single chapter early in the user guide which briefly defines each
concept, maybe with some examples.
2. A section at the start of each tutorial chapter which defines the
concepts that the chapter is going to cover.
3. Include the definition into the tutorial section which introduces the
concept.
4. A glossary and index at the end of the user guide.

We probably want to use a couple of these options. I think option 2 is a
good place to start.

A lot of the high-level material is actually there in the user guide.
It's just hard to find in the 200+ pages, and is inconsistently
structured. We could relatively easily re-arrange the existing content
to make things easier to find.

Perhaps a first pass could simply be to separate the existing chapters
into their various types:
1. start with early beginner tutorial chapters ('getting started',
'build script basics', 'java quickstart')
2. then special interest topics chapters ('more about tasks', 'logging',
'writing custom tasks', 'using ant')
3. then reference chapters ('the java plugin', 'Gradle command-line')

Some existing chapters would need splitting, I think (eg 'multi-project
builds', 'dependency management') or merging into other chapters (eg
'this and that').

Then, we can review each beginner tutorial, and add in empty or
placeholder sections for the missing stuff: missing concepts, and
missing high-level material for the concepts. I think even a section
with just a heading or a single sentence adds some value. And by
applying a consistent structure, it will become apparent what high-level
material is missing, and also provide a template for new material as we
add it.

> I don't want to migrate my build by doing copy/pastes that I don't
> understand, because this guarantees that in a few months from now, I
> still won't understand how my build works, much less how to modify
> it.  I will only switch to a new build system if I can completely
> understand how it works, philosophically and technically.

I absolutely agree. We want people to understand what's going on in the
build script, rather than just copying magic incantations they find via
google. It leads to a much better user experience, and is just less
frustrating for everyone.

>
> TestNG's build is pretty straightforward (although interestingly,
> Maven can't achieve it, I can go into details if you're curious) and
> the two things that I needed to get started are:
>
>     * How do I change the default source directories?
>     * How do I configure my classpath to point to local jar files?
>
> I ended up reading about variables called srcDirNames or something
> such, none of which are mentioned in that doc anywhere.  I still
> wasn't able to get these variables to work properly, by the way, so
> I'm still in the dark as to how to do this.  And I still don't know
> how to add local jar files to my compile and runtime classpath.  I'm
> guessing this involves specifying artifacts with some file:/// tricks
> or something like that, but I couldn't find any example anywhere (not
> just in your doc, I really mean anywhere in my web searches).
>
> My ant build has been working flawlessly for years and I'm very happy
> with it but I'm also always trying to streamline things and I think
> Gradle has the power to trim down my build files considerably, so I'd
> really like to get this working and see if I would be happy with the
> final result.
>
> Thanks for reading :-)
>

Thanks for the feedback. I think we can sort out the documentation so
other people don't suffer the same frustrations.


--
Adam Murdoch
Gradle Developer
http://www.gradle.org


---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email


Loading...