The other way to install the Mac Reference Library

2009-09-02 08:34:45 -08:00

Starting with Xcode 3.2, the Xcode installer package no longer includes a local copy of any developer documentation. Instead, you have to either go to the website (which is what the redesigned Documentation Viewer window does) or download the documentation within Xcode.

Both solutions have their own problems. Reading the docs on the website can be frustrating if you’re streaming or downloading something in the background. And downloading within Xcode is dubious if your internet connection is not super-fast or is flaky, because Xcode cannot resume downloads.

There is a third solution.

  1. In Xcode’s Preferences, click on an info button at the right edge of the list of docsets, or right-click on the docset and choose “Get Info”.
  2. Select the row labeled “Feed URL”, and copy it.
  3. In a text editor or text field, paste the text, then edit it (it’s the whole row, not just the value) down to the URL alone. There’s a period (full stop) at the end of the text; it’s not part of the URL, so make sure you delete that.
  4. Open the URL in a feed reader.
  5. On the most recent entry, copy the URL for the enclosure.
  6. Paste it into your download manager or browser Downloads window.

Assuming your download manager or browser supports resuming downloads, you now have a way to pause the download for any reason that may arise, and resume it from that point.

Of course, then you have to install what you downloaded. You’re probably not used to seeing xar files (although you’ve seen more than you think—flat packages are based on them), so you may not know what to do with them.

  1. Pop open a terminal. cd over to where you downloaded the xar archive.
  2. pushd /Developer/Documentation/DocSets
  3. sudo xar -xf ~+1/filename.xar
  4. Once that finishes, delete (or back up) the xar file.

Xcode’s Documentation Viewer window (or your browser) should suddenly be much quicker.

10 Responses to “The other way to install the Mac Reference Library”

  1. Dave M. Says:

    I’m a little confused here. I just checked my installation of Xcode 3.2 and not only do I have local copies of the documentation, but I have the ability to check for and install updates automatically (via a checkbox in the settings page).

    Not all the documentation is downloaded by default, there are several older manuals/docsets that you have to click a button to get Xcode to download for the first time. After that however, it keeps the documents up-to-date just fine.

    I don’t have to implement any of the “third solution” steps you showed.

    Am I missing something here?

  2. Peter Hosey Says:

    If you visited the Preferences, that’s why. Xcode starts downloading the two most important docsets immediately if you open the Documentation pane of the Preferences and don’t already have them, and maybe you have enough bandwidth that you didn’t notice, or maybe you did it at night and then went to bed and left your computer on overnight.

  3. Dale Gillard Says:

    Thanks Peter. I’ve found the doc downloading very unreliable. The Activity window eventually shows it starts downloading, then stops, and won’t restart. The UI doesn’t indicate why either.

  4. Jon H Says:

    I just wish the doc window didn’t open to the useless Xcode Quick Start.

  5. Dave M. Says:

    Peter, I have never had problems download the documentation ever. Actually, Xcode 3.2 is way better than previous versions since it only downloads one doc at a time. The older versions would attempt to download all the docs that needed updating all at once. I would have to go into the window and pause all the other docs, then do them one at a time.

    I have an average cable broadband connection that does 5Mbps down, so I don’t consider connection all that fast.

    I guess my main confusion here is that it sounds like the post is saying that the documentation is not available locally at all. When it clearly is.

  6. Peter Hosey Says:

    Dave M.: It’s not preinstalled locally; to have it locally, you must download it, as I say in the first paragraph of the post.

    And your connection is much faster than mine (768/128 kbps DSL). You can download the Core Reference in about 15 minutes. Depending on what you did after opening the Preferences, I can easily imagine you not seeing the download.

  7. Alessandro Says:

    And if you’re behing a proxy, the thirs solution is your only option.
    I, too, wish I could disable QuickHelp.

  8. Dan Morrow Says:

    This is interesting.

    However, I got to your page by looking for something else. We have Mac OS X Server, and we host a Software Update Server. What’s nice about this is that everyone in the company gets their software updates from our local machine, instead of Apple’s site. The server just downloads the updates, as they come in.

    It would be awesome if you know of a way to get the Software Update Server to host XCode documentation updates. I work with about 10 engineers, and those updates eat up a lot of external bandwidth.

  9. Dody Suria Wijaya Says:

    Peter, thanks. Internet was unreliable as well on my place and your tips help awfully a lot. For those who have fast and reliable internet connection, you do not have to use this guide (e.g. Dave M).

  10. Stephen Says:

    Thanks Peter, this was really helpful and explained why Xcode was still ‘Getting’ every time I launched it..

Leave a Reply

Do not delete the second sentence.