more detailed and targeted docs about installing from source

[zooko]

The current docs/install.html is short and sweet and readable and should work to get you to install from source on any platform (provided you are familiar all the ins and outs of compiling the various manual dependencies on your platform -- Crypto++ and pyOpenSSL are two that people sometimes have trouble with).

It would be nice to have a lot more detail for people who aren't intimately familiar with this stuff, or people who don't want to do the setuptools-centric "run-in-place" method described in docs/install.html.

Some set of interlinked HTML files should be constructed (drawing from the pool of experience that is encoded into the current docs/install-details.html) which provides some combination of (a) more details for particular platforms (for example, did you know that there's a tricky incompatibility between twisted and nevow and tahoe on Ubuntu Dapper?), (b) alternate install techniques -- "Just Get Prebuilt Debs", "Just Run easy_install allmydata-tahoe", "How To Use setuptools To Install Into Specific Places So That It Is GNU Stow Compatible", "How To Build Your Own Debs", and so on.

Justin believes, and I agree, that there should be a file for each platform -- e.g. docs/install-win32.html, docs/install-cygwin.html, docs/install-macosx.html, etc.

[zooko]

Hm. I think that it is possible that the improvements to the install/build process since we opened this ticket make it so that we do not need targeted docs for each platform. In particular, we no longer need to build Crypto++ separately, nor install Twisted. Hopefully soon we will also no longer need to install pyOpenSSL -- #402 (bug in Twisted, triggered by pyOpenSSL-0.7).

That will leave: g++, GNU make, Python, and OpenSSL as requirements that people have to manually satisfy. Fortunately OpenSSL and Python are included with the operating system on Mac.

[zooko]

I'm going to close this bug as "wontfix". My strategy for making it possible for people to install from source who are not Python experts (and by the way this is a goal that I highly value) is going to be to make the install process be automated instead of being documented.

[zooko]

Brian has persuaded me that this strategy may not be good enough for my goals -- there are plenty of ways where people could fail to install Tahoe from source while following the simple [docs/install.html], which failures could be fixed by more detailed instructions, including possibly instructions for specific platforms.

However, we don't want to delay 1.1 release while working on this issue, so I'm reopening this ticket and putting it into Milestone 1.1.1.

[zooko]

Merging in #194 (README.w32).

[arch_o_median]

I attempted to install using the ​docs/install.html instructions, and failed. By examining this thread I realized I needed pycrypto++ and pyopenssl. Once I installed these I was able to install according to the rest of the recipe.

[zooko]

Did you try v1.2.0? There is a known bug with that process, which is fixed in trunk. Here's the mailing list message about it:

​http://allmydata.org/pipermail/tahoe-dev/2008-August/000740.html

Thank you for the bug report!

By the way pycryptopp is handled automatically, it was only pyOpenSSL that had that problem.

[zooko]

Brian and I agreed on IRC that for the Tahoe 1.3.0 release we would add to install.html a link to a wiki page on allmydata.org. That wiki page would be for (a) platform-specific or installation-method-specific alternatives, (b) further detail which is useful for following the basic install-from-source plan that is in install.html.

(Items in category (b) would be candidates for subsequently moving from the wiki page into install.html itself.)

[warner]

Ok, I've added the InstallDetails wiki page, with everything that came to mind just now. It is linked from source:docs/install.html and the [Doc Doc] page.

Feel free to add more details to it as we discover them.