RFR: JDK-8071767 Improve names and dependencies for image targets

[Magnus Ihse Bursie]

On 2015-02-05 08:12, David Holmes wrote:
> Hi Magnus,
>
> Thanks for the detailed background - makes things a lot clearer! It 
> would be useful for a synopsis to be included in the makefile along 
> with the functional changes.

So I joined forces with Ingemar and extended his patch with some 
comments derived from my mail.

New webrev: 
http://cr.openjdk.java.net/~ihse/JDK-8071767-improved-global-make-targets/webrev.02

/Magnus

>
> David
>
> On 4/02/2015 10:20 PM, Magnus Ihse Bursie wrote:
>> On 2015-02-04 09:33, David Holmes wrote:
>>> On 3/02/2015 11:17 PM, Ingemar Aberg wrote:
>>>> Some of the target names in the makefiles are inconsistent and does 
>>>> not
>>>> clearly reflect what they do. They should be improved but the old 
>>>> names
>>>> should be kept as aliases for people who are used to them.
>>>>
>>>> Examples:
>>>>
>>>> images -> product-images
>>>> docs -> docs-image
>>>
>>> I find "images" and "docs" quite clear as-is. I don't understand what
>>> a "docs-image" might be. And "product" is totally subjective and
>>> easily confused with a "release" build versus fastdebug etc.
>>>
>>> Maybe because of things like "exploded-image" (which is what? what is
>>> the unexploded image?) the use of "image" alone is less clear, but
>>> still "product-image" doesn't seem right.
>>
>> Since I was the one suggesting these names, let me elaborate a bit.
>>
>> The driving force behind these name changes is the ongoing effort of
>> test co-location, that is integrating test source code more closely with
>> the product code, and integrating the build of said tests with the
>> existing build framework.
>>
>> So when historically the build system has, more or less (this is an
>> oversimplification but it's enough for this discussion), only built the
>> actual bits to be shipped to the customer (the "product"), this will no
>> longer be the case. So we need to have target names that clearly
>> separates wether we build the "product" (that is, the things we build
>> from the various "src" directories in the repos), from tests, and other
>> things we deliver (like documentation).
>>
>> If you have a better suggestion than "product", please let me hear! Just
>> not "jdk", it's overloaded in meanings as it is.
>>
>> As part of the Jigsaw M2 effort, we spent quite some time getting a more
>> consistent and predictable structure of the build output directory.
>> Unfortunately, we might not have communicated this effort clearly
>> outwords. :-( What we have, in the post-M2 world, is the following build
>> output structure:
>> $BUILD/
>>    support/ <-- here we put build-internal and intermediate files, such
>> as generated source or .o files
>>    jdk/ <-- here we put, like before, a "runnable"/"exploded" jdk.
>>    images/ <-- here we put the "deliverables" that is the final result
>> of the build
>>
>> I personally would have chosen a different name for the deliverables
>> than "images", but it was decided to keep this legacy name for practical
>> reasons. So, with this terminology, "images" means "the end result, our
>> deliverables".
>>
>> The images directory contains a number of, eh, images, like "jre" or
>> "jdk", or some other Oracle internal ones, or special Mac OSX bundles,
>> etc. Or the docs image.
>>
>> And now we are adding "images/test", that is, the test image.
>>
>> So, then, what would you expect to build when building "images"? Or when
>> building "all"?
>>
>> I argued that "all" should build all our images (that is, it's an alias
>> for "all-images"). And that "all" our images consisted of three types:
>> * the test image [test-image]
>> * the docs image [docs-image]
>> * the product images [product-images]
>>
>> I also argued that "images" has traditionally meant just the
>> product-images (and not docs), and thus should not include test-images
>> now either (in contrast to "all"). (This was by no means the way other,
>> more test-oriented people originally interpreted the target name.)
>>
>> So this change clarifies that
>>
>> all-images: product-images test-image docs-image
>>
>> and that we have a set of "traditional" targets which are now rather to
>> be considered aliases to targets with more standardized names, which has
>> developed as the build system has grown:
>>
>> default: exploded-image
>> jdk: exploded-image
>> images: product-images
>> docs: docs-image
>> all: all-images
>>
>> As for the name "exploded image", I think it's a good candidate for
>> Worst Name Ever. :-( I'd replace it in a second if I could come up with
>> a better name. Suggestions are welcome!
>>
>> So, I believe this is a good change that lays the foundation for a more
>> clear set of targets when we move forward with the test co-location.
>>
>> /Magnus