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

[Magnus Ihse Bursie]

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