diff options
author | travis%sedsystems.ca <> | 2008-04-04 11:47:16 +0000 |
---|---|---|
committer | travis%sedsystems.ca <> | 2008-04-04 11:47:16 +0000 |
commit | 09962dd12d30d488c0105afcac1e541c0475ab62 (patch) | |
tree | bffbf75b640ba720f132b34c2822313469fdd49d /docs/en/xml | |
parent | fdee1caf4cd0bf7045521863f2b45c5deb15ccf1 (diff) | |
download | bugs-09962dd12d30d488c0105afcac1e541c0475ab62.tar bugs-09962dd12d30d488c0105afcac1e541c0475ab62.tar.gz bugs-09962dd12d30d488c0105afcac1e541c0475ab62.tar.bz2 bugs-09962dd12d30d488c0105afcac1e541c0475ab62.tar.xz bugs-09962dd12d30d488c0105afcac1e541c0475ab62.zip |
Bug 239852 - Documentation changes for Windows support
Patch by bruce.armstrong@teamsybase.com, cleaned up by travis@sedsystems.ca
r=bugzilla@glob.com.au
Diffstat (limited to 'docs/en/xml')
-rw-r--r-- | docs/en/xml/installation.xml | 267 | ||||
-rw-r--r-- | docs/en/xml/modules.xml | 122 |
2 files changed, 253 insertions, 136 deletions
diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml index 33495d861..304204383 100644 --- a/docs/en/xml/installation.xml +++ b/docs/en/xml/installation.xml @@ -1,5 +1,5 @@ <!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> --> -<!-- $Id: installation.xml,v 1.85 2008/04/04 06:47:15 jake%bugzilla.org Exp $ --> +<!-- $Id: installation.xml,v 1.86 2008/04/04 06:47:16 travis%sedsystems.ca Exp $ --> <chapter id="installing-bugzilla"> <title>Installing Bugzilla</title> @@ -639,8 +639,8 @@ <para> By default, MySQL will limit the size of a table to 4GB. This limit is present even if the underlying filesystem - has no such limit or if you are using RAID. To set a higher - limit, follow these instructions. + has no such limit. To set a higher limit, follow these + instructions. </para> <para> @@ -795,20 +795,82 @@ <section id="http-iis"> <title>Microsoft <productname>Internet Information Services</productname></title> - <para>If you need, or for some reason even want, to use Microsoft's - <productname>Internet Information Services</productname> or - <productname>Personal Web Server</productname> you should be able - to. You will need to configure them to know how to run CGI scripts. - This is described in Microsoft Knowledge Base article - <ulink url="http://support.microsoft.com/support/kb/articles/Q245/2/25.asp">Q245225</ulink> - for <productname>Internet Information Services</productname> and - <ulink url="http://support.microsoft.com/support/kb/articles/Q231/9/98.asp">Q231998</ulink> - for <productname>Personal Web Server</productname>. + <para> + If you are running Bugzilla on Windows and choose to use + Microsoft's <productname>Internet Information Services</productname> + or <productname>Personal Web Server</productname> you will need + to perform a number of other configuration steps as explained below. + You may also want to refer to the following Microsoft Knowledge + Base articles: + <ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;245225">245225</ulink> + <quote>HOW TO: Configure and Test a PERL Script with IIS 4.0, + 5.0, and 5.1</quote> (for <productname>Internet Information + Services</productname>) and + <ulink url="http://support.microsoft.com/default.aspx?scid=kb;en-us;231998">231998</ulink> + <quote>HOW TO: FP2000: How to Use Perl with Microsoft Personal Web + Server on Windows 95/98</quote> (for <productname>Personal Web + Server</productname>). + </para> + + <para> + You will need to create a virtual directory for the Bugzilla + install. Put the Bugzilla files in a directory that is named + something <emphasis>other</emphasis> than what you want your + end-users accessing. That is, if you want your users to access + your Bugzilla installation through + <quote>http://<yourdomainname>/Bugzilla</quote>, then do + <emphasis>not</emphasis> put your Bugzilla files in a directory + named <quote>Bugzilla</quote>. Instead, place them in a different + location, and then use the IIS Administration tool to create a + Virtual Directory named "Bugzilla" that acts as an alias for the + actual location of the files. When creating that virtual directory, + make sure you add the <quote>Execute (such as ISAPI applications or + CGI)</quote> access permission. + </para> + + <para> + You will also need to tell IIS how to handle Bugzilla's + .cgi files. Using the IIS Administration tool again, open up + the properties for the new virtual directory and select the + Configuration option to access the Script Mappings. Create an + entry mapping .cgi to: + </para> + + <programlisting> +<full path to perl.exe >\perl.exe -x<full path to Bugzilla> -wT "%s" %s + </programlisting> + + <para> + For example: + </para> + + <programlisting> +c:\perl\bin\perl.exe -xc:\bugzilla -wT "%s" %s + </programlisting> + + <note> + <para> + The ActiveState install may have already created an entry for + .pl files that is limited to <quote>GET,HEAD,POST</quote>. If + so, this mapping should be <emphasis>removed</emphasis> as + Bugzilla's .pl files are not designed to be run via a webserver. + </para> + </note> + + <para> + IIS will also need to know that the index.cgi should be treated + as a default document. On the Documents tab page of the virtual + directory properties, you need to add index.cgi as a default + document type. If you wish, you may remove the other default + document types for this particular virtual directory, since Bugzilla + doesn't use any of them. </para> - <para>Also, and this can't be stressed enough, make sure that files such as - <filename>localconfig</filename> and your <filename class="directory">data</filename> - directory are secured as described in <xref linkend="security-webserver-access"/>. + <para> + Also, and this can't be stressed enough, make sure that files + such as <filename>localconfig</filename> and your + <filename class="directory">data</filename> directory are + secured as described in <xref linkend="security-webserver-access"/>. </para> </section> @@ -946,8 +1008,19 @@ <programlisting>5 0 * * * cd <your-bugzilla-directory> ; ./collectstats.pl</programlisting> - <para>After two days have passed you'll be able to view bug graphs from - the Reports page.</para> + <para> + After two days have passed you'll be able to view bug graphs from + the Reports page. + </para> + + <para> + <note> + Windows does not have 'cron', but it does have the Task + Scheduler, which performs the same duties. There are also + third-party tools that can be used to implement cron, such as + <ulink url="http://www.nncron.ru/">nncron</ulink>. + </note> + </para> </section> <section> @@ -1007,14 +1080,21 @@ which leave their bugs in the NEW or REOPENED state without triaging them. </para> <para> - - This can be done by - adding the following command as a daily crontab entry, in the same manner - as explained above for bug graphs. This example runs it at 12.55am. + This can be done by adding the following command as a daily + crontab entry, in the same manner as explained above for bug + graphs. This example runs it at 12.55am. </para> <programlisting>55 0 * * * cd <your-bugzilla-directory> ; ./whineatnews.pl</programlisting> - + + <para> + <note> + Windows does not have 'cron', but it does have the Task + Scheduler, which performs the same duties. There are also + third-party tools that can be used to implement cron, such as + <ulink url="http://www.nncron.ru/">nncron</ulink>. + </note> + </para> </section> <section id="patch-viewer"> @@ -1205,27 +1285,28 @@ AddType text/xml .rdf</screen> <section id="os-win32"> <title>Microsoft Windows</title> - - <para>Making Bugzilla work on Windows is still a painful processes. - The Bugzilla Team is working to make it easier, but that goal is not - considered a top priority. If you wish to run Bugzilla, we still - recommend doing so on a Unix based system such as GNU/Linux. As of this - writing, all members of the Bugzilla team and all known large installations - run on Unix based systems. - </para> - - <para>If after hearing all that, you have enough pain tolerance to attempt - installing Bugzilla on Win32, here are some pointers. - <![%bz-devel;[ - Because this is a development version of the guide, these instructions - are subject to change without notice. In fact, the Bugzilla Team hopes - to have Bugzilla reasonably close to "out of - the box" compatibility with Windows by the 2.18 release. - ]]> + <para> + Making Bugzilla work on Windows is more difficult than making it + work on Unix. For that reason, we still recommend doing so on a Unix + based system such as GNU/Linux. That said, if you do want to get + Bugzilla running on Windows, you will need to make the following + adjustments. </para> <section id="win32-perl"> <title>Win32 Perl</title> + <para> + Perl for Windows can be obtained from + <ulink url="http://www.activestate.com/">ActiveState</ulink>. + You should be able to find a compiled binary at <ulink + url="http://aspn.activestate.com/ASPN/Downloads/ActivePerl/" />. + The following instructions assume that you are using version + 5.8.1 of ActiveState. + </para> + </section> + + <section id="win32-perl"> + <title>Win32 Perl</title> <para>Perl for Windows can be obtained from <ulink url="http://www.activestate.com/">ActiveState</ulink>. You should be @@ -1237,47 +1318,60 @@ AddType text/xml .rdf</screen> <section id="win32-perlmodules"> <title>Perl Modules on Win32</title> - <para>Bugzilla on Windows requires the same perl modules found in - <xref linkend="install-perlmodules"/>. The main difference is that - windows uses <glossterm linkend="gloss-ppm">PPM</glossterm> instead of - CPAN. + <para> + Bugzilla on Windows requires the same perl modules found in + <xref linkend="install-perlmodules"/>. The main difference is that + windows uses <glossterm linkend="gloss-ppm">PPM</glossterm> instead + of CPAN. </para> <programlisting> C:\perl> <command>ppm install <module name></command> </programlisting> - <note> - <para>The above syntax should work for all modules with the exception - of Template Toolkit. The <ulink - url="http://tt2.org/download.html#win32">Template Toolkit website</ulink> - suggests using the instructions on <ulink - url="http://openinteract.sourceforge.net/">OpenInteract's website</ulink>. - </para> - - <para>The following commands will install the required packages - missing from the ActivePerl default installation: - </para> + <para> + The best source for the Windows PPM modules needed for Bugzilla + is probably the the Bugzilla Test Server (aka 'Landfill'), so + you should add the Landfill package repository as follows: + </para> - <programlisting> -<command>ppm repository add oi http://openinteract.sourceforge.net/ppmpackages</command> -<command>ppm install DBD-mysql</command> -<command>ppm install Template-Toolkit</command> -<command>ppm install TimeDate</command> - </programlisting> + <programlisting> +<command>ppm repository add landfill http://www.landfill.bugzilla.org/ppm/</command> + </programlisting> + <note> + <para> + The PPM repository stores modules in 'packages' that may have + a slightly different name than the module. If retrieving these + modules from there, you will need to pay attention to the information + provided when you run <command>checksetup.pl</command> as it will + tell you what package you'll need to install. + </para> </note> - </section> + <para> + <tip> + If you are behind a corporate firewall, you will need to let the + ActiveState PPM utility know how to get through it to acccess + the repositories by setting the HTTP_proxy system environmental + variable. For more information on setting that variable, see + the ActiveState documentation. + </tip> + </para> + </section> + <section id="win32-code-changes"> <title>Code changes required to run on win32</title> - <para>Bugzilla on win32 is mostly supported out of the box; one remaining issue is - related to bug email. To make bug email work on Win32 (until - <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=84876">bug - 84876</ulink> lands), the - simplest way is to have the Net::SMTP Perl module installed and - change this line in the file Bugzilla/Bugmail.pm:</para> + <para> + Bugzilla on win32 is mostly supported out of the box; one + remaining issue is related to bug email. To make bug email + work on Win32 (until + <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=49893">bug + 49893</ulink> lands), the + simplest way is to have the Net::SMTP Perl module installed and + change this line in the file Bugzilla/Bugmail.pm: + </para> <programlisting> open(SENDMAIL, "|/usr/lib/sendmail $sendmailparam -t -i") || @@ -1286,7 +1380,11 @@ open(SENDMAIL, "|/usr/lib/sendmail $sendmailparam -t -i") || print SENDMAIL trim($msg) . "\n"; close SENDMAIL; </programlisting> - <para>to</para> + + <para> + to + </para> + <programlisting> use Net::SMTP; my $smtp_server = 'smtp.mycompany.com'; # change this @@ -1304,28 +1402,33 @@ $smtp->dataend(); $smtp->quit; </programlisting> - <para>Don't forget to change the name of your SMTP server and the - domain of the sending email address (after the '@') in the above - lines of code.</para> + <para> + Don't forget to change the name of your SMTP server and the + domain of the sending email address (after the '@') in the + above lines of code. + </para> </section> <section id="win32-http"> <title>Serving the web pages</title> - <para>As is the case on Unix based systems, any web server should be - able to handle Bugzilla; however, the Bugzilla Team still recommends - Apache whenever asked. No matter what web server you choose, be sure - to pay attention to the security notes in <xref linkend="security-webserver-access"/>. - More information on configuring specific web servers can be found in - <xref linkend="http"/>. + <para> + As is the case on Unix based systems, any web server should + be able to handle Bugzilla; however, the Bugzilla Team still + recommends Apache whenever asked. No matter what web server + you choose, be sure to pay attention to the security notes + in <xref linkend="security-webserver-access"/>. More + information on configuring specific web servers can be found + in <xref linkend="http"/>. </para> <note> - <para>If using Apache on windows, you can set the <ulink - url="http://httpd.apache.org/docs-2.0/mod/core.html#scriptinterpretersource">ScriptInterpreterSource</ulink> - directive in your Apache config to avoid having - to modify the first line of every script to contain your path to - perl instead of <filename>/usr/bin/perl</filename>. + <para> + If using Apache on windows, you can set the <ulink + url="http://httpd.apache.org/docs-2.0/mod/core.html#scriptinterpretersource">ScriptInterpreterSource</ulink> + directive in your Apache config to avoid having to modify + the first line of every script to contain your path to perl + perl instead of <filename>/usr/bin/perl</filename>. </para> </note> diff --git a/docs/en/xml/modules.xml b/docs/en/xml/modules.xml index 3d4f6e556..81a12d7f5 100644 --- a/docs/en/xml/modules.xml +++ b/docs/en/xml/modules.xml @@ -24,13 +24,15 @@ a 'make' utility. The <command>nmake</command> utility provided with Microsoft Visual C++ may be used. As an alternative, there is a utility called <command>dmake</command> available from CPAN which is - written entirely in Perl. + written entirely in Perl. The majority of the links given below, however, + are to pre-compiled versions of the modules, which can be installed + on Windows simply by issuing the following command once you have + downloaded the PPD file (which may be packaged within a ZIP file): </para> <para> - As described in <xref linkend="modules-manual-download" />, however, most - packages already exist and are available from ActiveState or theory58S. - We highly recommend that you install them using the ppm GUI available with - ActiveState and to add the theory58S repository to your list of repositories. + <screen> + <prompt>></prompt> ppm install <filename.ppd> + </screen> </para> </note> </section> @@ -38,30 +40,39 @@ <section id="modules-manual-download"> <title>Download Locations</title> - <note> - <para> + <para> + <note> Running Bugzilla on Windows requires the use of ActiveState - Perl 5.8.1 or higher. Many modules already exist in the core - distribution of ActiveState Perl. Additional modules can be downloaded - from <ulink url="http://theoryx5.uwinnipeg.ca/ppms/" /> if you use - Perl 5.8.x or from <ulink url="http://cpan.uwinnipeg.ca/PPMPackages/10xx/" /> - if you use Perl 5.10.x. - </para> - </note> + Perl 5.8.1 or higher. Some modules already exist in the core + distribution of ActiveState Perl so no PPM link is given. + (This is noted where it occurs.) + </note> + </para> <para> + AppConfig: + <literallayout> + CPAN Download Page: <ulink url="http://search.cpan.org/src/ABW/AppConfig-1.56/lib/AppConfig.pm"/> + PPM Download Link: <ulink url="http://landfill.bugzilla.org/ppm/AppConfig.ppd"/> + Documentation: <ulink url="http://search.cpan.org/~abw/AppConfig-1.56/lib/AppConfig.pm"/> + </literallayout> + </para> + + <para> CGI: <literallayout> CPAN Download Page: <ulink url="http://search.cpan.org/dist/CGI.pm/"/> - Documentation: <ulink url="http://perldoc.perl.org/CGI.html"/> + PPM Download Link: Part of core distribution. + Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/CGI.html"/> </literallayout> </para> <para> Data-Dumper: <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/Data-Dumper/"/> - Documentation: <ulink url="http://search.cpan.org/dist/Data-Dumper/Dumper.pm"/> + CPAN Download Page: <ulink url=http://search.cpan.org/src/ILYAM/Data-Dumper-2.121/Dumper.pm"/> + PPM Download Page: Part of core distribution. + Documentation: <ulink url="http://search.cpan.org/~ilyam/Data-Dumper-2.121/Dumper.pm"/> </literallayout> </para> @@ -69,6 +80,7 @@ Date::Format (part of TimeDate): <literallayout> CPAN Download Page: <ulink url="http://search.cpan.org/dist/TimeDate/"/> + PPM Download Link: <ulink url="http://landfill.bugzilla.org/ppm/TimeDate.ppd"/> Documentation: <ulink url="http://search.cpan.org/dist/TimeDate/lib/Date/Format.pm"/> </literallayout> </para> @@ -77,6 +89,7 @@ DBI: <literallayout> CPAN Download Page: <ulink url="http://search.cpan.org/dist/DBI/"/> + PPM Download Link: <ulink url="http://landfill.bugzilla.org/ppm/DBI.ppd"/> Documentation: <ulink url="http://dbi.perl.org/docs/"/> </literallayout> </para> @@ -85,23 +98,26 @@ DBD::mysql: <literallayout> CPAN Download Page: <ulink url="http://search.cpan.org/dist/DBD-mysql/"/> + PPM Download Link: <ulink url="http://landfill.bugzilla.org/ppm/DBD-mysql.ppd"/> Documentation: <ulink url="http://search.cpan.org/dist/DBD-mysql/lib/DBD/mysql.pm"/> </literallayout> </para> <para> - DBD::Pg: + File::Spec: <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/DBD-Pg/"/> - Documentation: <ulink url="http://search.cpan.org/dist/DBD-Pg/Pg.pm"/> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/File-Spec/"/> + PPM Download Page: Part of core distribution. + Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/File/Spec.html"/> </literallayout> </para> <para> - File::Spec: + File::Temp: <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/File-Spec/"/> - Documentation: <ulink url="http://perldoc.perl.org/File/Spec.html"/> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/File-Temp/"/> + PPM Download Page: Part of core distribution. + Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/File/Temp.html"/> </literallayout> </para> @@ -109,44 +125,37 @@ Template-Toolkit: <literallayout> CPAN Download Page: <ulink url="http://search.cpan.org/dist/Template-Toolkit/"/> + PPM Download Link: <ulink url="http://landfill.bugzilla.org/ppm/Template-Toolkit.ppd"/> Documentation: <ulink url="http://www.template-toolkit.org/docs.html"/> </literallayout> </para> <para> - GD: + Text::Wrap: <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/GD/"/> - Documentation: <ulink url="http://search.cpan.org/dist/GD/GD.pm"/> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/Text-Tabs+Wrap/"/> + PPM Download Link: Part of core distribution. + Documentation: <ulink url="http://www.perldoc.com/perl5.8.0/lib/Text/Wrap.html"/> </literallayout> </para> - + <para> - Template::Plugin::GD: - <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/Template-GD/" /> - Documentation: <ulink url="http://www.template-toolkit.org/docs/aqua/Modules/index.html" /> - </literallayout> - </para> - - <para> - MIME::Parser (part of MIME-tools): + GD: <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/MIME-tools/"/> - Documentation: <ulink url="http://search.cpan.org/dist/MIME-tools/lib/MIME/Parser.pm"/> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/GD/"/> + PPM Download Link: <ulink url="http://landfill.bugzilla.org/ppm/GD.ppd"/> + Documentation: <ulink url="http://stein.cshl.org/WWW/software/GD/"/> </literallayout> </para> - </section> - - <section id="modules-manual-optional"> <title>Optional Modules</title> <para> Chart::Base: <literallayout> CPAN Download Page: <ulink url="http://search.cpan.org/dist/Chart/"/> - Documentation: <ulink url="http://search.cpan.org/dist/Chart/Chart.pod"/> + PPM Download Page: <ulink url="http://landfill.bugzilla.org/ppm/Chart.ppd"/> + Documentation: <ulink url="http://search.cpan.org/src/CHARTGRP/Chart-2.3/doc/Documentation.pdf"/> </literallayout> </para> @@ -154,6 +163,7 @@ GD::Graph: <literallayout> CPAN Download Page: <ulink url="http://search.cpan.org/dist/GDGraph/"/> + PPM Download Link: <ulink url="http://landfill.bugzilla.org/ppm/GDGraph.ppd"/> Documentation: <ulink url="http://search.cpan.org/dist/GDGraph/Graph.pm"/> </literallayout> </para> @@ -162,15 +172,26 @@ GD::Text::Align (part of GD::Text::Util): <literallayout> CPAN Download Page: <ulink url="http://search.cpan.org/dist/GDTextUtil/"/> + PPM Download Page: <ulink url="http://landfill.bugzilla.org/ppm/GDTextUtil.ppd"/> Documentation: <ulink url="http://search.cpan.org/dist/GDTextUtil/Text/Align.pm"/> </literallayout> </para> + <para> + MIME::Parser (part of MIME-tools): + <literallayout> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/MIME-tools/"/> + PPM Download Link: <ulink url="http://ppm.activestate.com/PPMPackages/zips/8xx-builds-only/Windows/MIME-tools-5.411a.zip"/> + Documentation: <ulink url="http://search.cpan.org/dist/MIME-tools/lib/MIME/Parser.pm"/> + </literallayout> + </para> + <para> - XML::Twig: + XML::Parser: <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/XML-Twig/"/> - Documentation: <ulink url="http://standards.ieee.org/resources/spasystem/twig/twig_stable.html"/> + CPAN Download Page: <ulink url="http://search.cpan.org/dist/XML-Parser/"/> + PPM Download Link: Part of core distribution. + Documentation: <ulink url="http://www.perldoc.com/perl5.6.1/lib/XML/Parser.html"/> </literallayout> </para> @@ -178,16 +199,9 @@ PatchReader: <literallayout> CPAN Download Page: <ulink url="http://search.cpan.org/author/JKEISER/PatchReader/"/> + PPM Download Link: <ulink url="http://landfill.bugzilla.org/ppm/PatchReader.ppd"/> Documentation: <ulink url="http://www.johnkeiser.com/mozilla/Patch_Viewer.html"/> </literallayout> </para> - - <para> - Image::Magick: - <literallayout> - CPAN Download Page: <ulink url="http://search.cpan.org/dist/PerlMagick/"/> - Documentation: <ulink url="http://www.imagemagick.org/script/resources.php"/> - </literallayout> - </para> </section> -</appendix> +</appendix> |