[39458] trunk/doc-new/guide/xml/installing.xml
Ryan Schmidt
ryandesign at macports.org
Thu Aug 21 19:57:28 PDT 2008
On Aug 21, 2008, at 21:00, markd at macports.org wrote:
>>> Personally, I'd prefer directing users to the place where the
>>> latest Xcode
>>> version is listed for the current OS (10.5) since it is a moving
>>> target.
>>> Otherwise we fix the guide in time more than absolutely necessary
>>> and
>>> commit ourselves to updating the guide for Apple updates anywhere
>>> such
>>> references are made. Also, saying "at the time of writing" seems
>>> not to
>>> help since there isn't a way to know what time that is for that
>>> particular
>>> text snippet, so it almost invites putting the date in parenthesis.
>>>
>>> I see that Apple's developer site now has a button named "Download
>>> Latest
>>> Xcode" [ http://developer.apple.com/tools/xcode/
>> ]http://developer.apple.com/tools/xcode/
>>>
>>> So I favor something like I pasted below. I can't even find Xcode
>>> 1.5 on
>>> Apple's site (though it must be there somewhere), and since we don't
>>> officially support 10.3 anymore I don't think anything needs to be
>>> said on
>>> that.
>>>
>>> ---------------------
>>> Download and install the latest version of Xcode Tools by
>>> clicking the
>>> button "Download Latest Xcode" here:
>>> ([ http://developer.apple.com/tools/xcode/)
>> ]http://developer.apple.com/tools/xcode/). Do not install Xcode
>> Tools
>>> from a Mac OS X install DVD unless you verify that you are
>>> installing the
>>> latest version as listed on Apple's developer site; older versions
>>> often
>>> cause port install failures.
>>>
>>> If you are installing MacPorts on Mac OS X 10.4, download and
>>> install
>>> Xcode 2.5
>>> ([ http://connect.apple.com/cgi-bin/WebObjects/MemberSite.woa/wa/
>> ]http://connect.apple.com/cgi-bin/WebObjects/MemberSite.woa/wa/
>>> getSoftware?bundleID=19907)
>>> ---------------------
>>>
>>> How does that seem?
>>
>> I made the change specifically in response to a user who was confused
>> when Xcode 2 did not work with Leopard, because he couldn't find a
>> newer version on Apple's site:
>>
>> [ http://lists.macosforge.org/pipermail/macports-users/2008-August/
>> ]http://lists.macosforge.org/pipermail/macports-users/2008-August/
>> 011312.html
>>
>> He went to ADC: Downloads: Mac OS X. The latest version I find there
>> is 2.2.1.
>
> But he wasn't led astray by the Guide. The Guide can and needs to be
> improved, but doesn't necessarily help to modify guide text to try to
> solve a specific problem that arose because a user ignored that
> very Guide
> text, especially when the text that was in front of the user's face
> (Apple's) before they clicked download were ignored. Here is
> Apple's text
> at that link.
>
> ----------
> Xcode Tools 2.2.1:
> Xcode 2.2.1 is an update for the Mac OS X v10.4 Xcode Tools suite.
> Please see the Read Me document for more details and installation
> instructions.
> -----------
>
> What needs to be fixed is Apple's ADC site, but nowhere I know of
> in the
> Guide do we point users there.
>>
>> Now, you and I know to go to ADC: Downloads: Developer Tools instead,
>> which is where all versions of the Developer Tools (except Xcode 2.0)
>> are located, going back to the December 2002 Developer Tools for
>> Jaguar before it was even called Xcode. But if a user doesn't know
>> that Xcode 2.2.1 isn't the latest, they won't go looking for a newer
>> one.
>>
>> I don't like the "Download Latest Xcode" button because it only gives
>> you the latest Xcode for Leopard; it doesn't give you the latest
>> Xcode for Tiger or Panther.
>
> Giving the link to the "latest Xcode" for 10.5 was only one part of my
> suggestion:
>
> ------------------
> Download and install the latest version of Xcode Tools by clicking the
> button "Download Latest Xcode" here:
> (http://developer.apple.com/tools/xcode/). Do not install Xcode Tools
> from a Mac OS X install DVD unless you verify that you are
> installing the
> latest version as listed on Apple's developer site; older versions
> often
> cause port install failures.
>
> If you are installing MacPorts on Mac OS X 10.4, download and install
> Xcode 2.5
> (http://connect.apple.com/cgi-bin/WebObjects/MemberSite.woa/wa/
> getSoftware?bundleID=19907)
> -------------------
>
> The suggested text does tell you where to find Xcode 2.5 for 10.4,
> which
> the current instructions do not, and finding it isn't as easy as it
> seems.
> Telling someone what they need and showing them where it are
> different
> things. Do to the magic of hyperlinking, we can do both at once and I
> think this is a slight improvement.
>
>> I do want to continue supporting Panther
>> as much as possible. I know we have at least one active Panther user
>> on the list. I see no reason to cut off support for Panther at this
>> time.
>
> Nobody is "cutting off" anything. The support is what it is. It is a
> question of what is recommended. I would not like to give the
> impression
> that we provide better support that we actually do, and support for
> 10.3
> is pretty darn weak. We all know that we aren't prepared to do
> much to
> actively support 10.3
I think most of my ports work on Panther. If they don't, I'll gladly
take bug reports.
> so how long will it be before in response to a MP
> developer's suggestion that (at the very least) it is wise to avoid
> 10.3
> if possible that we hear: "But on page 1 at the top of the Guide it
> states
> requirements for 10.3 (implying it is supported), and now you're
> telling
> me it isn't supported?" And we do say that, and I think we've had
> this
> discussion many times before.
Then we should state on page 1 that support for Panther and non-Mac
OSes is not guaranteed. It is official MacPorts policy that only the
latest two Mac OS X releases are supported [1] so we should state
this in the Guide.
[1] http://lists.macosforge.org/pipermail/macports-dev/2008-June/
005393.html
Note: The Guide already contains examples of "darwin 7" platform
statements, which could also be construed to mean that Panther is
supported.
I do think it is a good idea to list the requirements of MacPorts in
the Guide, and certain versions of Xcode are required. This came up
before, and it was decided that we would gladly trade user time for
developer time -- better to have the user spend time downloading a
new Xcode than to have a developer spend time to figure out that a
user's problem was caused by an old Xcode. We are not in control of
Apple's web sites, but we are in control of the Guide, hence it is
useful to list there the minimum versions of Xcode that should be used.
I don't like your link to download Xcode 2.5 directly for the same
reason you didn't like me stating that Xcode 2.5 is the latest
version for Tiger -- what if it changes? I think it's better to teach
the user to fish: show them where Xcode releases are posted and let
them find the latest version.
> But look, I know I'm acting as a self-appointed documentation Nazi,
> and
> probably coming off as too argumentative,
No worries -- I'm glad someone feels responsible for guiding the Guide!
> but the truth is I think there
> are unstated assumptions at work in discussions about the Guide. I
> think
> failure to observe a certain rules ruins a document over time, and
> that
> disagreement on those implicit assumptions is the source of most of
> the
> disagreements on MP docs. I have several in mind:
>
> 1) One I'm always pushing is basically the 80/20 rule (or 95/5 or
> insert_your_own_numbers here). We have a mailing list, and it will
> always
> be used and needed, and a wiki. Some questions are best answered
> by the
> list, and trying to answer certain questions that fall in the 20%
> in the
> Guide will destroy it over time. The Guide is an attempt to document
> certain things, not everything. A document can't be all thing to all
> people.
I believe the Guide should document everything you need to know about
using MacPorts. I would not include information about how to use any
specific port, and I wouldn't include ProblemHotlist-type stuff which
is really just descriptions of bugs which will be fixed.
> 2) No duplication of text unless absolutely necessary. This is a
> volunteer project and we must minimize the effort required for
> documentation, or it will seem futile to have good documents in a
> reasonable length of a volunteer's time. Soon, in a future
> release, the
> man pages will be sourced oet of the Guide and this is a big step in
> having accurate and maintainable documents.
Before manpages can be sourced out of the Guide, the information
currently in the manpages needs to be put into the Guide... :)
Also, I pointed out recently how much duplication of text we already
have, which is captured here:
http://www.macports.org/docs.php
> 3) Minimalism is good, because people only have so much time to read.
> Everything that can be said shouldn't be. All text needs to
> support the
> main purpose of the document.
That's true.
> I think probably we should hash out this stuff as a community, and I'm
> always willing to submit this sort of thing to a vote. I think a
> certain
> ruthless adherence to these principals will get us a better Guide
> in the
> end since comprehensive documentation is difficult and none of us
> get paid
> for this. I can look at almost any part of the Guide and think "That
> could be a lot better", but I think when trying to do so I think there
> should be overall consideration of the document design principles.
> BTW, I
> do intend to start in on the unfinished sections of the Guide very
> soon,
> and also address the tickets on it. Hopefully in a matter of weeks.
Are the document design principles documented somewhere? :)
>> I agree "as of this writing" isn't good without a date, and that I
>> shouldn't have created the situation where we have to update the
>> Guide with "latest" information about Xcode releases, even if they
>> are infrequent. Instead, how about we list a minimum Xcode version?
>> The minimum supported Xcode version for MacPorts is 3.0 on Leopard,
>> 2.4 on Tiger and 1.5 on Panther, as seen in the MacPorts configure
>> script:
>>
>>
>> case "$XCODE_VERSION" in
>> 1.[[0-1]]*|2.[[0-1]]*)
>> AC_WARN(This version of Xcode Tools is not supported)
>> AC_WARN(Please upgrade at [ http://connect.apple.com/
>> ]http://connect.apple.com/)
>> ;;
>> 1.[[2-4]]*|2.[[2-3]]*)
>> AC_WARN(This version of Xcode Tools is out of date)
>> AC_WARN(Please consider upgrading as some ports fail compiling)
>> ;;
>> 1.5*|2.4*|3.*)
>> dnl Supported version
>> ;;
>> *)
>> ;;
>> esac
>
> I prefer to let the scripts do their job and warn the user
> appropriately
> without duplicating the script messages in the documentation.
> Principal
> #2. :)
The problem is that the script in which this is implemented is the
configure script, which is not a script a user will encounter if
installing MacPorts the usual way, from a dmg. Getting MacPorts to
check the Xcode version during normal use is an as yet outstanding
ticket.
http://trac.macports.org/ticket/12794
> Please don't take me as being rude or argumentative. I just have a
> vision
> for the docs I'd like to argue for and to put forth some working
> assumptions that I've always used for the Guide. I think
> discussing these
> issues as a community is a good thing.
Agreed!
More information about the macports-dev
mailing list