Debian Codegraph @

INSTALL

raw
1 NOTES FOR UPGRADERS:
2
3 I added an index to the metadata table in the postgres setup in
4 version 0.31 and in the MySQL setup in version 0.40 - this really
5 speeds up RecentChanges on larger wikis. See the 'Changes' file
6 for details on applying the index to existing databases. I've not
7 done any benchmarks on SQLite yet, so I'm leaving that alone for now.
8
9 HOW TO INSTALL THIS:
10
11 This module can be installed just like any other standard Perl module:
12
13 perl Makefile.PL
14 make
15 make test
16 make install
17
18 You may wish to use your local version of 'make' (e.g. 'nmake' on
19 Windows.) On most systems 'make install' requires you to have root
20 privileges.
21
22 'perl Makefile.PL' will ask a few questions about which databases
23 it can use in the 'make test' stage - the default is to only run those
24 tests that don't need external test databases. It is recommended that
25 you test with as many backend combinations as your system will allow.
26
27
28 *****************************************************
29 **** ****
30 **** THESE TESTS ARE DESTRUCTIVE. ****
31 **** DO NOT RUN THEM ON A DATABASE THAT CONTAINS ****
32 **** OR EVER WILL CONTAIN LIVE DATA. ****
33 **** ****
34 *****************************************************
35
36 *****************************************************
37 **** ****
38 **** THE DATABASE VALUES YOU GIVE HERE WILL BE ****
39 **** STORED IN Wiki::Toolkit::TestConfig AND ****
40 **** WILL BE USED FOR FUTURE INSTALLS OF THIS ****
41 **** AND RELATED MODULES. ****
42 **** ****
43 *****************************************************
44
45
46 For noninteractive installation, or to provide defaults for interactive
47 installation, set the following environment variables to suitable values.
48 Leave them blank or explicitly set them to 'undef' if you don't want
49 to test that particular backend.
50
51 WIKI_TOOLKIT_MYSQL_DBNAME # If 'undef', following two variables are ignored
52 WIKI_TOOLKIT_MYSQL_DBUSER
53 WIKI_TOOLKIT_MYSQL_DBPASS
54 WIKI_TOOLKIT_MYSQL_DBHOST # Leave blank if database is local
55 WIKI_TOOLKIT_PG_DBNAME # If 'undef', following two variables are ignored
56 WIKI_TOOLKIT_PG_DBUSER
57 WIKI_TOOLKIT_PG_DBPASS
58 WIKI_TOOLKIT_PG_DBHOST # Leave blank if database is local
59 WIKI_TOOLKIT_DBIXFTS_MYSQL # NOTE: Any non-blank value other than 'undef'
60 # or '0' signifies 'test this'
61
62 Second and subsequent successful runs of 'perl Makefile.PL' will use
63 the testing setup specified in the first run and hence will not ask
64 questions or look for options in environment variables. To over-ride
65 this behaviour and be asked the questions again, do 'perl Makefile.PL -s'
66 or set the environment variable WIKI_TOOLKIT_RERUN_CONFIG to something
67 non-blank. If you do this then your previous answers will be offered
68 as defaults.
69
70 When re-running configuration (ie with the '-s' flag or
71 WIKI_TOOLKIT_RERUN_CONFIG set), explicit settings in environment variables
72 will over-ride settings specified during previous runs.
73
74 If you provide settings for a backend that you don't have the drivers
75 installed for (DBD::mysql, DBD::Pg, DBIx::FullTextSearch) then they
76 will be ignored.
77
78 POST INSTALL:
79
80 You'll want to run the wiki-toolkit-setupdb script to set up the initial
81 database tables. This script will have been installed with the rest
82 of the distribution. There is a hole in this documentation here.
83
84 If you are upgrading from an earlier version of Wiki::Toolkit, and there
85 has been no change to the database schema in the newer releases,
86 wiki-toolkit-setupdb will do nothing. If there has been a change to the
87 schema, it will leave your existing data alone but update the table schema.
88
89 user-setup-mysql-dbixfts.pl
90
91 This final script will, if used, set up DBIx::FullTextSearch indexes and
92 attempt to index any existing data. Because of this, it must be run *after*
93 user-setup-mysql.pl
94
95 Note that installing Wiki::Toolkit *does* install wiki-toolkit-setupdb for
96 you, but does *not* install user-setup-mysql-dbixfts.pl (this is mainly
97 because the name is really ugly).
98
99 TESTING NOTES:
100
101 'perl Makefile.PL' will ask some questions about which backends to run
102 the tests for. You will need to create at least one test database
103 before you run the tests, and your test user will need to be able to
104 create and drop tables in that database.
105
106 Postgres notes:
107
108 You can create a database from the shell:
109 shell$ createdb wiki_toolkit_test
110
111 And give a user password access by editing pg_hba.conf (which lives
112 somewhere like /var/lib/postgres/data/pg_hba.conf) to contain the line:
113
114 local wiki_toolkit_test md5
115
116 Then in psql run something like:
117 postgres=# create user wiki with password 'wiki';
118
119 You can give a database to a user by using psql to update the
120 pg_database table -- the datdba UID comes from the pg_user table.)
121
122 MySQL notes:
123
124 Something like "grant all privileges on wiki_toolkit_test.* to
125 wiki@localhost identified by 'wiki'" will create a suitable user and
126 give it password access to, and all required privileges on the test
127 database.
128
129 PREREQUISITES:
130
131 The following modules *must* be installed before you try to build this:
132
133 * DBI
134 * Digest::MD5
135 * HTML::PullParser
136 * Test::More
137 * Test::Warn
138 * Test::MockObject (version 0.07 or later)
139 * Text::WikiFormat (version 0.45 or later)
140 * Time::Piece
141
142 You will also need the relevant DBD database driver module for whichever
143 storage backend you plan to use, for example one of:
144
145 * DBD::mysql
146 * DBD::Pg
147 * DBD::SQLite (version 0.21 or later)
148
149 In addition, if you want to use the DBIx::FullTextSearch backend, you will
150 need:
151
152 * DBIx::FullTextSearch (version 0.71 or later)
153 * Lingua::Stem
154
155 For the Search::InvertedIndex backend you need:
156
157 * Search::InvertedIndex
158
159 And finally, the Postgres and SQLite backends require the following for
160 testing purposes:
161
162 * Hook::LexWrap