more detailed and targeted docs about installing from source #282

New Issue

zooko · 2008-01-23T03:14:17Z

zooko commented

2008-01-23 03:14:17 +00:00

The current source: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 source:docs/install.html.

Some set of interlinked HTML files should be constructed (drawing from the pool of experience that is encoded into the current source: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. source:docs/install-win32.html, source:docs/install-cygwin.html, source:docs/install-macosx.html, etc.

The current source: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 source:docs/install.html. Some set of interlinked HTML files should be constructed (drawing from the pool of experience that is encoded into the current source: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. source:docs/install-win32.html, source:docs/install-cygwin.html, source:docs/install-macosx.html, etc.

zooko added the

labels 2008-01-23 03:14:17 +00:00

zooko added this to the undecided milestone 2008-01-23 03:14:17 +00:00

zooko changed title from ~~install-details.html, install-win32.html, install-cygwin.html~~ to more detailed and targeted docs about installing from source

2008-01-23 03:14:42 +00:00

zooko commented

2008-05-31 01:06:38 +00:00

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.

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 modified the milestone from undecided to 1.1.0

2008-05-31 01:12:02 +00:00

zooko commented

2008-06-04 01:04:13 +00:00

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 added the

wontfix

label 2008-06-04 01:04:13 +00:00

zooko closed this issue

2008-06-04 01:04:13 +00:00

zooko commented

2008-06-05 18:16:07 +00:00

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.

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 removed the

wontfix

label 2008-06-05 18:16:07 +00:00

zooko reopened this issue

2008-06-05 18:16:07 +00:00

zooko commented

2008-06-05 19:29:25 +00:00

Merging in #194 (README.w32).

arch_o_median commented

2008-08-16 00:45:24 +00:00

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.

> I attempted to install using the [docs/install.html](http://allmydata.org/trac/tahoe/browser/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 commented

2008-08-16 14:10:09 +00:00

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.

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 commented

2008-09-17 17:32:50 +00:00

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.)

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.)

zooko added this to the 1.3.0 milestone 2008-09-17 17:32:50 +00:00

zooko removed their assignment 2008-09-17 17:32:50 +00:00

warner was assigned by zooko

2008-09-17 17:32:50 +00:00

warner commented

2008-09-17 23:13:44 +00:00

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.

Ok, I've added the [InstallDetails](wiki/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.

warner added the

fixed

label 2008-09-17 23:13:44 +00:00

warner closed this issue

2008-09-17 23:13:44 +00:00

Sign in to join this conversation.