kvirc-data 4:4.2.0-2build1 / usr / share / kvirc / 4.2 / doc / INSTALL-Win32.txt

-------------------------------------------------------------------------------
KVIrc4 win32 compiling howto (WIP)                                 by CtrlAltCa
-------------------------------------------------------------------------------

This paper describes how to successfully compile a working copy of KVIrc 4.x
under Microsoft Windows operating systems.



-------------------------------------------------------------------------------
Prerequisites
-------------------------------------------------------------------------------

- A Microsoft Windows operating system

  [Needed to run KVIrc into, mandatory]

  - xp or 2003 server, preferably with at least service pack 2
  - vista, preferably not :p
  - seven or 2008 server

  Notice: DOS-based Windows operating systems (95,98,se,me) are not officially
  supported by KVIrc. Anyway, if you're still using such an old OS then you
  have worst problems than this...

  Notice: Windows 2000 may work, but is not officially supported anymore.
  Differences in its network stack and the difficulty to retrieve packages
  of kvirc dependencies still working on win2000 make compiling kvirc an
  overkill job.
  
- CMake from Kitware

  [Configuration tool; needed to compile KVIrc, mandatory]

  Download the tool from http://www.cmake.org. The package you want is called
  "Windows (Win32 Installer) cmake-<version>-win32-x86.exe" (version may vary).

  You need at least version 2.6.4 to compile KVirc. Avoid version 2.8.0; use 
  version 2.8.2 instead.

  Recent versions of the cmake installer will ask if you want to add cmake to
  the system PATH: you don't need it.


- Qt 4 from Nokia

  [Graphic library, mandatory]

  You need at least Qt 4.6.0 upwards fo get a fully working KVIrc.
  We suggest you to get the "Qt SDK for Open Source C++ development on
  Windows" you can get here: http://qt.nokia.com/downloads/sdk-windows-cpp

  The Qt SDK includes the Qt libraries and a working mingw environment, so you
  won't need to install one manually.

- MinGW from the MinGW team

  [Compiler; needed to compile KVIrc, mandatory]

  If you installed the Qt SDK >= 4.6.0, you already have MinGW installed and
  you can jump to the next requisite. Otherwise you need to install MinGW 
  manually: refer to http://www.mingw.org/wiki/InstallationHOWTOforMinGW
  Please note that you need to install gcc4 (gcc3 could work but is not supported).

- Perl for Win32

  [Programming language; needed for documentation creation; optionally can
  be used for scripting support; may also be used to compile OpenSSL by
  yourself (see the related paragraph below)]

  Any win32 version will work; We advice you to use the distribution provided
  by ActiveState. It's called ActivePerl and you can find at
    http://www.activestate.com/activeperl/downloads/
  You want the "Free Community Edition" package.

  Perl is needed to extract documentation from the source files and generate
  help files for kvirc.

  Some perl releases misses dmake; if you get a strange error at compilation
  time, run the following command from cmd prompt (start->run->cmd):

    # ppm install dmake

- Zlib compiled for Win32

  [Compression library; needed for many stuffs, mandatory]

  MinGW offers a zlib package: You'll need to download from 
  http://sourceforge.net/projects/mingw/ the packages:

      libz-1.2.3-1-mingw32-dll-1.tar.gz
      libz-1.2.3-1-mingw32-dev-1.tar.gz

  Search them on the MinGW project files download page.

  Install the lib somewhere (like c:\zlib) and remember its path.

- OpenSSL compiled for Win32

  [Enc/Decrypt library; needed to secure your irc sessions, optional]

  To compile KVIrc for your own use you can download a precompiled
  package from http://www.slproweb.com/products/Win32OpenSSL.html
  The package you want is called "Win32 OpenSSL v0.9.8l" (version number may
  vary; there should be a notice like "Recommended for software developers" 
  in the package description). Any recent version should work; general rule: 
  more recent usually means more secure.

  Newer OpenSSL versions from www.slproweb.com need a specific version of
  Microsoft Visual Studio 2008 runtimes to work (this sucks): so if you plan
  to create a  redistributable kvirc package, our advice is to compile
  OpenSSL by yourself using MinGW/MSYS and then use your libs.

  To compile OpenSSL by yourself:
   - download the latest source from http://www.openssl.org
   - move it somewhere inside the msys root directory (C:\MinGW\msys\1.0\)
   - open the MinGW shell and locate the package
   - unpack the package (you need to do it from the MinGW shell since it
     contains symlinks)
   - enter in the created directory
   - run "./config shared"
   - run "make" and then "make install"
   - grab the entire installation directory (eg: C:\MinGW\msys\1.0\local\ssl)
     and copy it in a more accessible path (like C:\OpenSSL)

  Whatever way you choose, install OpenSSL somewhere (like C:\OpenSSL)
  and remember the path.

- Python for Win32

  [Programming language; optional scripting support]

  Any win32 version will work; We advice you to use the version you can find
  at http://www.activestate.com/activepython/downloads/ .
  You want the "Free Community Edition" package.

  Please note that we are currently supporting the 2.x version of python 
  (currently 2.6). Python3000 (aka python3k) is not backwards compatible 
  and supported by now.

- GNU GetText for Win32

  [Localization tools; needed to translate kvirc interface into your
  own language; required if you're building a redistributable package,
  otherwise optional]

  We advice you to use the version you can find at 
  http://gnuwin32.sourceforge.net/packages/gettext.htm,
  follow the "Setup program" link.
  Install the package somewhere (like c:\gettext) and remember the path.

- GNU Sed for Win32

  [Tool; needed to tidy kvirc translation files, optional]

  We advice you to use the version you can find at 
  http://gnuwin32.sourceforge.net/packages/sed.htm,
  follow the "Setup program" link.
  
  Install the package somewhere (like c:\sed) and remember the path.

- Subversion cli for windows

  [Versioning tool; needed for cmake to automatically set the correct 
  revision number in kvirc build; can be overridden (see below)]

  Any version will work; Recently the subversion guys went nuts and despite
  an official download page exists http://subversion.apache.org/packages.html
  it requires you to download from a third party website. Those websites will
  push you to download their "better" subversion client or needs registration.

  If you don't want to install subversion cli because you are already using
  another subversion tool (like TortoiseSvn), you can just force the correct
  svn revision passing to cmake the -DMANUAL_REVISION=xxxx parameter.

- Nullsoft scriptable install system (NSIS)

  [Installer packages creator; needed if you want to create an installer 
  package for kvirc]

  Get it at http://nsis.sourceforge.net/Download ; the package you want 
  is called "nsis-2.46-setup.exe" (version numbers may vary).



-------------------------------------------------------------------------------
Further reccomended download if you plan to develop KVIrc:
-------------------------------------------------------------------------------

- GNU Debugger (gdb) for Win32:

  [Dev Tool: Debugger; optional]

  Download it from the MinGW website.

- StraceNT (aka strace for Win32)

  [Dev Tool: tracer; optional]

  Download it from http://www.intellectualheaven.com/ .


-------------------------------------------------------------------------------
Compilation
-------------------------------------------------------------------------------

Download KVIrc sources from KVIrc's website, a mirror or using svn (see 
instructions on KVIrc website about how to do that). From now on I'll assume
that you have saved the sources in C:\KVIrc

Go to the C:\KVIrc directory an create a "build" folder in it.
This may be done either via Windows explorer or via a command prompt
in the following way:

  # cd C:\KVIrc

  # mkdir build
  # cd build

Now copy the win32_run_cmake.bat script from the C:\KVIrc\doc directory
to the build directory

  # copy ..\doc\win32_run_cmake.bat .\

Now edit the file you just copied by filling in the paths (you did
write them down, don't you? :).

Run the win32_run_cmake.bat script.

  # win32_run_cmake.bat

This should invoke the cmake executable and configure kvirc for you.

If it complains about missing libraries then you haven't properly
edited the paths in the win32_run_cmake.bat file. Check again.
Note that the "bin" subdirectories generally aren't included in the path.

You may also try to use the CMake gui for the compilation. Just be aware
of the %PATH% variable defined in the win32_run_cmake.bat script. If you
screw up %PATH% CMake may refuse to start or the mingw make may crash.
Note also that you must tell the graphical configurator that you want
the "MinGW Makefiles" as output.

Once cmake did its job (it will tell you that it's ready to compile kvirc)
you can just run the mingw make program.

  # mingw32-make.exe

The compilation may spit out some warnings: just ignore them (unless
you're a cool developer.. in that case: fix them!).
If it runs without errors then you can also run make install:

  # mingw32-make.exe install

This should create a working kvirc executable for you in the build\release
directory. With some experience you may also get mingw to create a debug
build.

Simply running kvirc from that directory should work :) . If instead it's
complaining of some missing dll's, you may need to copy those dlls into
 kvirc binary directory (in our example: c:\KVirc\build\release) or to get
those dlls recognized and loaded automatically from your OS.

If you want to create an installer package, you need to:

1) fill the binary directory (in our example: c:\KVIrc\build\release) with 
  all the files that cmake doesn't create: 
  - needed dlls: 
        - Qt: QtCore4, QtGui4 (mandatory); QtNetwork4, QtSvg4, QtWebkit4,
            QtXml, QtXmlPatterns (used in objects module);
        - Zlib: libz.dll (aka libz-1.dll, zlib.dll, ...);
        - Openssl: libeay32.dll, libssl32.dll (names may vary);
        - MinGW: mingwm10.dll, libgcc_s_dw2-1.dll
        - Perl: perl512.dll (version number may vary);
        - Python: python26.dll (version number may vary);
        - Amip: ac.dll / ac.ini (adds plug'n'play support for amip)
		Choose the right dlls depending on your build options: for a debug
		build you'll need debug version of Qt libraries (eg. QtCored4)

  - qt plugins:
        These have to be placed in a subdirectory named qt-plugins
		(in our example: c:\KVirc\build\release\qt-plugins).
        Currently KVIrc can use 4 types of plugins: codecs, imageformats,
		phonon_backend, sqldrivers. Create a subdirectory and name it with the
		type name of the plugins you'll place inside it;
		(eg: c:\KVirc\build\release\qt-plugins\imageformats\qjpeg4.dll)
        You can find them inside the "plugins" directory in the Qt Sdk.
		Choose the right dlls depending on your build options: for a debug
		build you'll need debug version of Qt plugins (eg. qjpegd4.dll)

  - locale translations:
        If you did not install or disabled gettext, your release folder misses
		the "locale" folder tipically containing translation files. This means
		kvirc won't be able to translate its user interface.
		As a workaround, you can get translation files somewhere, create the
		"locale" folder and manually place translations inside it.

  - help file:
        If you did not install or disabled perl, your release folder misses
		the "help" folder tipically containing user help. This means
		kvirc internal help will contain no help pages.
		As a workaround, you can get help files somewhere, create the
		"help/en" folder and manually place help files inside it.

2) run the KVIrc.nsi script from the build directory (c:\kvirc\build in our example) .
  Just compile it using nsis and an installer package will be generated.


-------------------------------------------------------------------------------
Common errors, pitfalls, ..
-------------------------------------------------------------------------------

- On modules compilation we get a warning like this one:
  ----------
  C:\kvirctrunk\src\modules\clock\libkviclock.cpp:242: warning: `KVIrc_module_info' initialized and declared `extern'
  ----------
  This is a simple warning, it doesn't block compilation or affects any functionality.

- During the compilation, we get a warning like this one:
  ----------
  C:/kvirctrunk/src/kvilib/system/kvi_time.h:0: Warning: No relevant classes found. No output generated.
  ----------
  In the compilation we call qt's moc to parse headers files and expand qt macros; 
  that warning simply means that moc found nothing to expand in that header file. We can fix this 
  removing headers that doesn't need to be moc-ed from the lists in CMakeLists.txt.

- * Windows Vista and 7 Users * If you have UAC enabled (default setting) and KVIrc is installed in the Program Files folder and you have opted to use the portable setting, then KVIrc's data files will be found in the VirtualStore folder, typically: C:\Users\[UserName]\AppData\Local\VirtualStore\Program Files\KVIrc\ If you plan on using the portable setting, it is recommended that you install KVIrc in a non UAC protected folder.