README
Strawberry Perl 5.22.3.1 modified for Greenstone
"32bit Portable edition (without USE_64_BIT_INT) version" which comes zipped
__________________________________________________

29 Nov 2018

Upgrading our Windows Strawberry Perl from 5.18.x to the final 5.22.x release, which is 5.22.3.1
by following the same instructions as when we created the 5.18.x perl.zip under the instructions from 26 July 2016 from further below:

	1. Download the "Strawberry Perl 5.22.3.1 (2017-01-15)" "32bit without USE_64_BIT_INT" version from http://strawberryperl.com/releases.html
	2. Extract it, then:
	3. copy the *.dll, *.bat and *-config files from the c\bin subdirectory into the perl\bin subdirectory. [1]
	4. put this StrawberryPerl_For_GS_README.txt file into its perl subfolder.
	5. Zip up the perl subfolder as perl.zip and upload to main/trunk/release-kits/shared/windows/perl.zip 
	6. Make the new Strawberry Perl's perl SUBFOLDER the new PERL_HOME environment variable and put its bin subfolder on the PATH. For example, in setenv.bat or in a Greenstone's "local" subfolder's gs3-setup.bat file. (Or set up the new PERL_HOME in the Windows System env vars, and adjust PATH there.)

We upgraded from 5.18.x to 5.22.x because our gsmysql.pm file turns on "mysql_enable_utf8mb4" for decoding the utf8 content in the database to get unicode aware strings. While this worked on the Ubuntu machine which came with Perl 5.22, our Strawberry Perl 5.18 on Windows did not decode the data coming out the database. The upgrade to Strawberry Perl 5.22 updated the included DBD and DBI perl packages for mysql (database driver and interface), which now did the automatic decoding.

Note that setting "mysql_enable_utf8mb4 => 1" during the DBI->connect() call is no longer accepted as a configuration setting and results in the error message, despite working on Ubuntu:
	Character set 'utf8mb4' is not a compiled character set and is not specified in the 'c:\Program Files\MySQL\MySQL Server 5.1\\share\charsets\Index.xml' file
	DBI connect('host=127.0.0.1','root',...) failed: Can't initialize character set utf8mb4 (path: c:\Program Files\MySQL\MySQL Server 5.1\\share\charsets\)
	at C:\Users\Me\GS3svn\gs2build\perllib/gsmysql.pm line 287.

Instead of switching on mysql_enable_utf8mb4 upon connect(), we get the same effect by doing the following TWO operations after connection, so this code in gsmysql.pm is now uncommented and should work on both Windows and Linux:
	my $stmt = "set NAMES '" . $db_enc . "'";
	$dbh->do($stmt) || warn("Unable to set charset encoding at db server level to: " . $db_enc . "\n"); # "set names utf8mb4;" tells MySQL to use UTF-8 for communication
	$dbh->{mysql_enable_utf8mb4} = 1; # tells DBD::mysql to decode the data

[1] https://stackoverflow.com/questions/20990786/perl-mysql-error-libmysql-dll explains that the errors they describe,
they had to copy their Strawberry Perl's file c\bin\libmysql_.dll into perl\vendor\lib\auto\DBD\mysql
Since I have not yet encountered such errors, I did not do this step. Maybe this may come in useful in future.


Oddly, when you run "perl -v" using this new Strawberry Perl, it says it's version 5.22.1 instead of 5.22.3.x.

----------------------------------------------------------------------------------------------------------------
	
README
Strawberry Perl 5.18.2.2 modified for Greenstone
"32bit PortableZIP edition (no USE_64_BIT_INT) version"
__________________________________________________

26 July 2016

Because of the fix that Georgy Litvinov needed to make to deal with surrogate pair/invalid UTF-8 errors when processing some PDFs, this left warnings being printed out when using perl 5.8 to build any GS collections. Moreover, perl 5.8 was too old to handle the fix and would print out errors on documents that had such problematic characters. We found perl 5.16 could cope. However, we had to move to Strawberry since Active Perl would only offer the latest versions of perl (5.24 at the time of writing) for free. We had to shift to perl 5.18 since that's the perl version installed on Mac OS Yosemite, and we wanted to keep our other GS systems in sync with that.

We downloaded StrawBerry Perl from "5.18.2.1" "32bit PortableZIP edition (no USE_64_BIT_INT)" from http://strawberryperl.com/releases.html
( http://strawberryperl.com/download/5.18.2.1/strawberry-perl-no64-5.18.2.1-32bit-portable.zip )

Versions 5.18.4 and 5.18.2.1, although available, were problematic. Their perl executables for the "32bit PortableZIP edition (no USE_64_BIT_INT)" versions came up as having Trojans in them as per Symantec endpoint protection. So we shifted to the previous version: 5.18.2.1.


Strawberry Perl is a Perl for Windows.

After unzipping the download, the README file says:
  If you want to use Strawberry Perl Portable not only from portableshell.bat,
  add c:\myperl\perl\site\bin, c:\myperl\perl\bin, and c:\myperl\c\bin
  to PATH variable

(where myperl is the folder into which StrawberryPerl was extracted)
  
perl\site\bin is empty. In fact, all of perl\site is empty except for subfolders. So there's no need to add this to the PATH.

It was however initially necessary to add c\bin to the PATH to get GLI to launch and build a collection. But there are several locations in Greenstone that make use of perl\bin, such as build.xml's perl-for-building target. As changing all of them to include c\bin as well may get complicated, the solution now is to merge the extracted perl's c\bin subfolder with the extracted perl's perl\bin subfolder. The .dll, .config and .bat files from c\bin seem enough (leaving out .exe), although so far it seems that c\bin\libexpat-1_.dll on its own suffices for running GLI and building. Neverthless, we're merging all dll files of c\bin into perl\bin, in case any of the other dlls there may be needed (such as libexslt-0_.dll).


This produces the cut-down version of Strawberry Perl 5.18.4 for Greenstone that we're now using since 26 July 2016.
