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