We sometimes see people on IRC confused about why they can't build JRuby the first time they check out it. I see this myself all the time when people in Oracle ask me how to experiment with JRuby.

BUILDING.md is currently a little confusing about this, or at least it is for me.

Initially, it says that you need to 'fully bootstrap the environment' and that you do this using mvn or mvn package.

However, it later says that if you want to run tests, you need to 'bootstrap the dev environment' by running mvn -Pbootstrap. But I've already 'bootstrapped' haven't I? In fact I think I 'fully' bootstrapped. And I was told that it 'only needs to be done once'. That doesn't seem to be the case. I think the confusion here is that this separate bootstrap phase is for when you want to run tests. The other bootstrap phase is just to normally build. However they're both called 'bootstrap' and one claims to 'fully' do the process, when really it doesn't.

I think I've also seen people told to use mvn install as some part of bootstrapping, but BUILDING.md doesn't mention this at all, except where it says that mvn install starts the new build. Wait I thought mvn package did that? Does it build something or install something? Why would I need to install anything to run tests in the source tree? Can someone clarify what mvn install does.

In general I find these terms very confusing. Bootstrap (either of them) doesn't really do any kind of bootstrapping as I understand it. Bootstrap makes it look like JRuby is going to be used to build some phase of JRuby. That's not happening is it? I think they both just install dependencies, don't they? In practice, I end up blindingly trying combinations of mvn clean package -Pboostrap install until things work.

Maybe I'm ignorant of how Maven is normally used, but everyone I work with who tries out JRuby for the first time comes back to me with the same confusion. Can we get some definitive clarity, and maybe some more explicit names for some of these phases?