MySQL Bugs: #57163: http://dev.mysql.com/doc/refman/5.5/en/windows-source-build.html is outdated

Bug #57163	http://dev.mysql.com/doc/refman/5.5/en/windows-source-build.html is outdated
Submitted:	1 Oct 2010 11:09	Modified:	8 Dec 2010 2:57
Reporter:	Vladislav Vaintroub	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:		OS:	Any
Assigned to:	Paul DuBois	CPU Architecture:	Any

Description:
This page is very old and does not resemble real situation anymore.

1. It references Windows 2000 - this OS is officially pronounced dead , any support for it by the vendor has ended. Neither we support Windows 2000.

2. It mentions compilers that would not be able to compile MySQL anymore (VS2005, VS2003) as supported. VS2008 and VS2010 can compile MySQL as of today.

3. has reference to old SDK-less VS2005 Express (which is not very useful when compiling MySQL).
Meanwhile VS2010 is the "default" express edition, while VS2008 is refered to as "old". Still, documentation suggests to use Windows 2003 SDK with VS2005 express, and that combination cannot compile MySQL Server.

4."Cygwin might be necessary if you want to run the test script or package the compiled binaries and support files into a Zip archive. (Cygwin is needed only to test or package the distribution, not to build it.) Cygwin is available from http://cygwin.com. "

Cygwin is not necessary . A decent native Windows perl is necessary to run tests , and only for that. Windows perl is either Strawberry Perl or ActiveState Perl. No bash scripts are used to make a ZIP, this functionality is integrated into build, i.e packaging is done with CPack.

5.
"3GB to 5GB of disk space.
The exact system requirements can be found here: http://msdn.microsoft.com/vstudio/Previous/2003/sysreqs/default.aspx and http://msdn.microsoft.com/vstudio/products/sysreqs/default.aspx "

- First link is broken, second one does not mention any system requirements.

On the bright side, the section about bison is almost good and still current :)

However, there are still hard to parse sentences:

"After installing the package, modify your path to include the bison binary"

It would be better understandable if it said "PATH environment variable" and "directory where bison.exe is located"

"and ensure that this binary is accessible from Visual Studio. "
Huh? CMake will complain if it does not find bison, and if it finds, Visual Studio will find it too.

How to repeat:
Read http://dev.mysql.com/doc/refman/5.5/en/windows-source-build.html

Thank you for the bug report.

Totally agree with Vladislav. We need to improve this part of the documentation.
I'm listing here some other issues (Ref. Man rev. 23349).

1. At page http://dev.mysql.com/doc/refman/5.5/en/windows-source-build-cmake.html it is written that

"6. Test the server. The server built using the preceding instructions expects that the MySQL base directory and data directory are C:\mysql and C:\mysql\data by default. If you want to test your server using the source tree root directory and its data directory as the base directory and data directory, you need to tell the server their path names. You can either do this on the command line with the --basedir and --datadir options, or by placing appropriate options in an option file."

That's right. The problem is that new users do not know where to locate mysqld.exe and data directory. Please write that, after building, mysqld can be found in the directory sql\Debug (replace Debug with Release, if you have compiled a Release rather than a Debug) and that the data directory can be found in the sql directory. You might want to add in the doc the command to start the server:

pth-to-source\sql\Debug>mysqld.exe --basedir="pth-to-source\sql" --datadir="pth-to-source\sql\data"

2. It is written also that

"When the server is running in standalone fashion or as a service based on your configuration, try to connect to it from the mysql interactive command-line utility."

Please write also that "you can find mysql.exe in the client\Debug directory (replace Debug with Release, if you have compiled a Release rather than a Debug)."

3. It is written that:

"When you are satisfied that the programs you have built are working correctly, stop the server. Now you can install the distribution. One way to do this is to use the make_win_bin_dist script in the scripts directory of the MySQL source distribution"

Now we use cpack (see http://forge.mysql.com/wiki/CMake). We need to document this in the Ref. Man.

4. In the page about make_win_bin_dist (http://dev.mysql.com/doc/refman/5.5/en/make-win-bin-dist.html) - if we will maintain it - we could add a short note to inform users on where the zip archive will be located after creation (in the root directory of source). This would help new users that just have compiled for the first time.

As per make_win_bin_dist script, I think it would be a good idea to add a line at the end of the code to inform users: something like $NOINST_NAME ".zip created in " $DESTDIR as well as adding a script parameter to pass DESTDIR when invoking make_win_bin_dist. Of course if make_win_bin_dist is an out-of-date script which will be deprecated it doesn't make sense to improve it. If it does make, please let me know and I'll add a separate feature request for this.

5. It is written that

"After installation, set up and start the server in the same way as for binary Windows distributions. This includes creating the system tables by running mysql_install_db."

I think we don't need this anymore because if we use the new method to build the archive, data directory is included.

Will handle as part of documenting WL#5161.

Thank you for your bug report. This issue has been addressed in the documentation. The updated documentation will appear on our website shortly, and will be included in the next release of the relevant products.

The source-installation instructions in the 5.5 manual have been rewritten for CMake:

http://dev.mysql.com/doc/refman/5.5/en/source-installation.html