On Feb 19, 2007, at 3:31 PM, Juan Manuel Palacios wrote:

Hello guys! I'm going over some more documentation in my quest to advance on the 1.4 release, and I have some question for you guys about some undocumented options in the porsts.conf file. What exactly do the following do?

-) porttrace: sets trace mode on by default, no need to pass -t?

That appears to be the case, though I'm not going to spend the time making 100% sure

-) portverbose: kinda self explanatory, but I wasn't able to figure out what verbosity level is enabled, -v or -d?

-v

-) xcodeversion & xcodebuildcmd: Xcode related block in base/src/ darwinports1.0/darwinports.tcl is rather involved, so I wasn't able to gather much information on these....

That block detects the current version of xcode and sets those variables. xcodeversion has several possible settings, but the important bit is that Xcode of version 2.1 or later will have "2.1" be the value of that variable (according to the comments, no need was seen to know if it's later than 2.1). xcodebuildcmd gets set to the proper command to use in order to build an Xcode project from the command-line - basically this is intended for systems with pbxbuild instead of xcodebuild. -- Kevin Ballard http://kevin.sb.org eridius@macports.org http://www.tildesoft.com

Hello Paul! On Feb 20, 2007, at 1:32 AM, Paul Guyot wrote:

Juan,

I am confused. These so-called "options" are undocumented but should not be used by any user because their semantics could change any time. For example, xcodeversion only means how to handle xcode related tools and the most frequent value ("2.1"), as Kevin notes it, only means 2.1 or higher, but once we encounter an incompatible version of xcode, we will need to add a new value and update the semantics. We certainly do not want users to override this setting by putting whatever they think this would mean, this "option" is set by MacPorts infrastructure and it's better to keep users away from it. All that, including portverbose, porttrace, etc. were never intended to be options users could configure, they are just a way to express some information through the whole program.

In fact, I do not understand why you found those in your ports.conf file. Mine is based from MP's ports.conf.in which does not mention those "options": http://svn.macosforge.org/projects/macports/browser/trunk/base/doc/ ports.conf.in

Finding out which "options" are up for user interaction (and therefore documentable) and which aren't was also one of my explicit goals; comments like yours, "stay away from those!", is what I was looking for with my mail. I didn't get all of them from a standard ports.conf file, I was reading into the bootstrap_options variable that gets initialized in dportinit in base/src/darwinports1.0/darwinports.tcl. So help me here build the final list. "Options" that are not meant for user interaction and therefore should *not* be documented are: -) xcodeversion -) xcodebuildcmd -) porttrace -) portverbose (why would you keep this one from being user customizable?) -) libpath? (from reading dportinit, it seems to me like this is a dangerous one, but you didn't say anything about it) -) auto_path? (likewise) -) master_site_local (created by jkh in r5004, reportedly as a customizable option meant to "(...) allows portfetch.tcl to go first to a local distfiles cache, if available, before going out over the net to try and get it by less efficient means.", but reading base/src/darwinports1.0/darwinports.tcl around line 450 and base/src/port1.0/portfetch.tcl around line 190 doesn't tell me much what the option does and how I could document it) Thanks for your help! Regards,... -jmpp

On Feb 20, 2007, at 4:07 AM, Paul Guyot wrote:

...

-) xcodeversion -) xcodebuildcmd -) porttrace -) portverbose (why would you keep this one from being user customizable?)

Please do not touch those.

Agreed on all counts but one. Why should we want to keep users from turning verbose mode on by default? If anything, I think that setting would help us, cutting down time spent on the initial stages of support ("did you remember to pass the -v flag to port(1)?"). Now, I'm not saying we ship ports.conf.in with the option turned on out of the box, only that we can advertise its existence if needed and therefore we should documented. All that said, of course, thinking I'm understanding its purpose correctly... am I? Does that option also do something else (that we don't want users messing with) that I'm missing? In a nutshell, why do you feel we should hide it along with the others?

...

-) libpath? (from reading dportinit, it seems to me like this is a dangerous one, but you didn't say anything about it)

libpath is simply ${prefix}/share/darwinports/Tcl/ This one could be documented, but I have yet to understand the interest of changing the default value.

I not only see no interest in changing it but also some danger in doing so, ${prefix}/share/darwinports/Tcl/ being where MP installs an important part of its runtime tcl files and libraries (but I could, of course, be mistaken again...). But in any case we agree on this one, steer clear from it ;-) I just wanted to make sure about it.

...

-) auto_path? (likewise)

auto_path is a standard Tcl variable, documented in library(n). MP code just plays with it, in particular to append libpath to it.

Hands off it!

...

-) master_site_local (created by jkh in r5004, reportedly as a customizable option meant to "(...) allows portfetch.tcl to go first to a local distfiles cache, if available, before going out over the net to try and get it by less efficient means.", but reading base/src/darwinports1.0/darwinports.tcl around line 450 and base/src/port1.0/portfetch.tcl around line 190 doesn't tell me much what the option does and how I could document it)

This one works like the MASTER_SITE_LOCAL environment variable, and in fact is set to this value during runtime. The value is appended to the list of mirrors before doing a fetch.

Appended or prepended? Jordan's comments in r5004 and "set master_sites [concat $env(MASTER_SITE_LOCAL) $master_sites]" in portfetch.tcl would lead me to understand the latter. But in any case,....

Jordan might have used this feature at some point, it corresponds to very specific scenarios where you deploy MacPorts on several machines and you host the distfiles somewhere on your local network, for example by sharing a flat version of /opt/local/var/db/dports/distfiles/. I am wondering if anyone (except maybe Jordan) is using that today and might be interested in using it. It still means having a good idea of what is going on in the fetch phase and how to flatten the distributed files. The behavior could be broken with some rewrite of the fetch code that would help us having mirrors, and I would personally not care about maintaining this feature. In a nutshell, I would not document it.

Agreed. Personally I don't see much added value in documenting it if it's not something that will work by simply assigning a value to the key in ports.conf. Something more complex and that requires tweaking elsewhere (where users will regularly *not* look) will be immediately deemed as broken, thus generating unnecessary support requests. Hands off it!

Paul

-jmpp