This is a bug not so much in gradle but in its documentation. Before @Lance_Java was so kind as point me in the right direction on flattening the copyspec, I went down the path of attempting to use CopySpec.rename for this purpose. I believe this method is misdocumented
This documentation says:
rename
CopySpec rename(Closure closure)
Renames a source file to a different relative location under the target directory. The closure will be called with a single parameter, the name of the file. The closure should return a String object with a new target name. The closure may return null, in which case the original name will be used.
However, my experimenting showed that the parameter is merely the name of the file without any path information prepended to it. Therefore, it is difficult to see how this method could be used to “rename” a source file to a different relative location under the target directory. My goal was to do exactly that, assuming that I could strip path information off the passed filename, but there was no such information. I suppose you could ADD path information to move the file somewhere else but it’s pretty hard to remove it when it isn’t there to begin with. This method seems most suited to actually renaming the file, rather than to changing its location.
Yes, I’ve confirmed this is possible. Also doing stuff like rename { "../$it" } or rename { "$buidDir/stuff/$it" } also works if you want to completely override the target directory. Using eachFile { } works well for this purpose as well.
I think the wording “relative location” is what is unclear here. It’s also actually inaccurate since you can use rename to move the file to a non-relative location. I think I’d just change that first sentence to say “Renames a source file.”. Thoughts?
I agree with you. “relative location” sort of implies that there is path information there, and that threw me off the scent. It wasn’t until I wrote some debugging code that I could see why nothing was being renamed. I assumed I was getting a full path, and I wasn’t.
My other thought is that @Lance_Java’s excellent suggestion to use fileTree.files as a “flatten mapper” (like Ant has) is completely undocumented and ought to be mentioned. I imagine this might be a relatively common use case and it would help to find out about it somewhere, maybe in the DSL or JavaDocs. I spent at least an hour scanning through your docs and was amazed to find after all that that there was a simple solution (after initially expecting there to be one and being disappointed that there didn’t seem to be one.)
You might also want to investigate my unpleasant discovery that specifying a copyspec with"../" rather than the correct "..' produces a very cryptic error message. I don’t know what the answer is, documentation, improved error messages. But this is the sort of thing that sends newbies (like me) running out of the room with their hair on fire.
I’ve improved the wording here to remove “relative location”.
I’ve added an explicit javadoc to FileTree for this method mentioning that it returns a ‘flattened’ collection.
Improving error messages in general is something we are wanting to address in the near future. There are a lot of awful cryptic messages as a result of simple (and common) mistakes in build scripts that very much need some polish.
