Re: [jamboost] boost-build.jam documentation issues

From: Andrey Melnikov (melnikov_at_[hidden])
Date: 2005-08-11 17:13:06

David Abrahams wrote:
> Andrey Melnikov <melnikov_at_[hidden]> writes:
> 
> 
>>David Abrahams wrote:
>>
>>>Andrey Melnikov <melnikov_at_[hidden]> writes:
>>
> it reports that the file can't be found
> on its internal version of $(BOOST_BUILD_PATH), which is misleading.

IC now.

>>Do we have multiple branches in CVS? 
> 
> 
> We have a 1.33 release branch, which you should probably not touch at
> this point. You can make your own branch if you want to.
> 
What are the reasons to have a private branch? The only reason I see now 
is that someone will be able to review my changes before integrating 
them branch into the main branch.

Do we need this kind of isolation between the developers? Do we use it now?

>>How we are going to separate BB in the future? Do we want it to
>>remain in main Boost distribution? 
> 
> 
> Yes.
> 
> 
>>I think it would be better to ship BB as a separate package 
> 
> 
> It is being shipped also as a separate package.
> 
> 
>>or at least not inside BOOST_ROOT.
> 
> 
> I don't see why that would be better. At any rate, it seems like a
> very unimportant change to make.

Yep. I'm kind of brainstorming here. I'm just looking for bad things and 
compiling a large TODO. I'm not going to start from low-priority things. 
But I think such quirks are worth of documenting them in TODO so they 
won't lost.

>>>>Should http://www.boost.org/tools/build/jam_src/ be merged into bbv2 
>>>>documentation tree some day?
>>>
>>>
>>>Probably not. 
>>
>>I meant into bbv2 developer/extender reference. Not into user
>>reference. Now it's outside of bb documentation tree.
> 
> 
> I know what you meant.

Do you mean that you we not going to merge jam_src documentation even 
into bbv2 developer/extender reference?

>>I don't know anything about these translation plans. Are they
>>documented somewhere? 
> 
> 
> Yes, in the mailing list archive. You have a lot of catching up to
> do. Please try to use the discussion history here as a way to get up
> to speed.

I think it would be nice to merge the results of all mailing list 
discussions into main documentation tree one day. But it isn't a high 
priority task.

>>Do we want to cancel Jam language and rewrite BB in Python? 
> 
> 
> Probably, eventually. First, we are going to rewrite all of the BBv2
> guts in Python. You can build bjam --with-python so that it embeds a
> Python interpreter. That allows the jam language to remain for
> Jamfiles while we rewrite the internal logic.

Do you mean that you are going to rewrite the BB core in Python, while 
users will still use Jam? Do you want users to start writin Jamfiles in 
Python one day?

>>>>Also, what is the reason to have so many boost-build.jam files? I think 
>>>>we can live just with the file located at root.
>>>
>>>Which ones are you talking about? The one in the root of BBv2 is used
>>>to forward its work on to the one in kernel/
>>
>>Take a look at all these boost-build.jam found in Boost CVS:

<snip>

>>1) Are all these files really required?
> 
> 
> Yes. The ones in the test subdirectory are being used... for
> tests of the build system!

I understand that private boost-build.jam are required in order to test 
boost-build.jam lookup and execution. I reviewed the files and 
understood that most of them redirect to local bootstrap.jam for testing 
purposes.

What about

boost\tools\build\v1\example\boost-build.jam
boost\tools\build\v2\example\boost-build.jam
boost\tools\build\v2\test\boost-build.jam

They just redirect to main boost-build. They should not point to kernel 
and IMO can be safely removed.

One reason not to remove them is that example/ look similar to user's 
projects directory so this boost-build.jam illustrates the recommended 
usage scenario.

>>2) Does all these files point to the right place?
> 
> 
> Yes.
> 
> 
>>Not only boost-build in the top directory is misleading. 
> 
> 
> What's misleading about it?

That it points to "kernel". I tried to use example\boost-build.jam 
(which points to kernel/ too) as a template for my own boost-build.jam 
and ended with having kernel there.

I think it should be documented that it's not a good idea to point to 
kernel despite it works.

>>For example, why boost\tools\build\v2\example\boost-build.jam points
>>to ../kernel, and not to ..?
> 
> 
> No good reason, I'm sure. Maybe that should be fixed.

See above.

>>Also, why do we have build-system.jam bootstrap.jam boost-build.jam in 
>>the top directory? Can we put them into kernel/ folder, so the top 
>>folder isn't cluttered with files useless for an end user?
> 
> 
> I don't know. Maybe. But why does an end user care about the
> internal directory structure of BBv2?

Internals aren't documented yet. So users dig in the core jamfiles and 
good structure will help them.

>>Should we move other such useless files to a new subfolder?
> 
> 
> What are you assuming is useless?

boost-build.jam bootstrap.jam build-system.jam generators_prototype.py 
hacking.txt nightly.sh release_procedure.txt roll.sh

End users don't need these files. So moving them deeper will make the 
structure clearer.

> Most of the things you're poking at here don't rate highly on my scale
> of "confusing things about BBv2."

Yep. It's just a TODO list.

>>Should we separate
>>- bb core (kernel, build, toolsets, options, util)
>>- documentation/examples
>>- internal bb developer stuff (debian new notes python test)
>>- user-modified settings and user extensions?
> 
> 
> Maybe. Again, I think these are of little importance at this stage.

I agree.

>>>According to the code, it's SystemRoot
>>>
>>> path = [ modules.peek : SystemRoot ] $(user-path) ; 
>>>
>>>Is there a better default place for a site-wide configuration on
>>>Windows?
>>
>>I think that even %SystemDrive%\ is still better that %SystemRoot%.
>>
>>The recommended place is SHGetFolderPath(CSIDL_COMMON_APPDATA). We can 
>>approximate that call with 
>>HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\Shell 
>>Folders\Common Appdata or with %ALLUSERSPROFILE%\Application Data
> 
> 
> I'm not a Windows expert, so I'll take your word for it.

http://msdn.microsoft.com/en-us/dnw2kcli/html/W2Kcli_chapter4.asp

I'm not the best Windows programmer in the world either. So I'd like 
this decision to be reviewed by other Windows developers.

>>Also, what are the reasons to have toolsets configured in
>>user-config, and not in site-config? I don't see any scenarios when
>>users would like to have different toolset configurations. 
> 
> 
> We did see those scenarios.

For example? Are they in the mail list?

>>The only thing which should be configured by each user separately is
>>maybe the default toolset. 
> 
> 
> Please, a little less presumption.

It's just my opinion. I'm just trying to learn the design principles of 
BB and rationale for everything in it. I won't able to write good 
documentation if I don't understand the underlying principles so I'm 
asking questions and saying naive things.

> Maybe my site administrator has Python-2.3 installed and I want to
> test against a Python-2.4 installed in my personal local directory (or
> think GCC versions if you prefer).

For VC it isn't possible to have private installations. And if all 
installations are global, there is no need to have private config files.

For example in your scenario you put both 2.3 and 2.4 into site-config 
and use python-2.3 on bjam command line if you need 2.3, just like with VC.

I see the rationale now. Thank you for explanation.

>>Also there are performance reasons. 
> 
> Performance reasons for what?
> 
For not having every installed toolset configured in site-config.jam. I 
mean that if each user has only toolsets he really needs in his 
user-config, BB initialization time is lower as fewer Init rules are run.

Andrey