Getting Started/Build/Windows/emerge: Difference between revisions

    From KDE TechBase
    (some clarifications)
    (some more words about emerge, save chunk of work)
    Line 1: Line 1:
    ''emerge'' is a tool to build the KDE sources and its third party requirements on MS Windows. It is the '''easy''' way to build KDE on MS Windows.
    ''emerge'' is a tool to build the KDE sources and its third party requirements on MS Windows. It is the '''easy''' way to build KDE on MS Windows.
    == Introduction ==
    Emerge is a tool that can build the different parts of kde and its dependencies under windows. We created this tool to automate and simplify the build process under windows. We try to build all packages that we offer in the kde installer with emerge. That has some advantages for us:
    * it is easy for people to join us:
    Before emerge it was quite some work to set a system up for development. There were some quirks, which were documented in some mailing lists, but you had to remember them or you ran into an already solved problem again, etc.
    Now to get a development machine you need a windows computer, need to install python and subversion and do the emerge checkout. Then execute emerge to build what you want to build. This is easy for developers coming from windows to KDE, and also for KDE developers coming to windows.
    * it is easy for us to do (nightly/continuous/release/reproducable/...) builds:
    With emerge you can build the whole software stack (lowlevel libs, qt, kdelibs, things above that) with only one command. You can start that build, and some hours later you can check, if it worked, or if something broke. So we can spot problems easier and earlier. We can also start with a "naked" windows computer without any other installed software and bootstrap kde on it. That ensures, that no hidden dependencies on some pieces of software sneak in, because then the builds on a "naked" computer would break and show the problem.
    * it is easier to collaborate:
    We can test the same emerge build description for a package on different windows versions/computers before we do binary releases. People can also add build descriptions for new packages to the subversion repository.
    This emerge tool was inspired by the Gentoo emerge tool.


    == Set up ==
    == Set up ==
    Line 28: Line 40:
    *NOTE from a user: The applications gimp, inkscape and graphviz are also a problem. To make shure that there goes nothing wrong i stripped my path to contain only what i needed to build.
    *NOTE from a user: The applications gimp, inkscape and graphviz are also a problem. To make shure that there goes nothing wrong i stripped my path to contain only what i needed to build.


    === Compiling ===
    ''emerge'' uses either the MinGW ("Minimalist GNU for Windows") GCC compiler and tools to build Qt and KDE from source code or one of the Microsoft Compilers (> Visual Studio 2003).
    Currently, there is no dependency on the compilers in any of the packages.  So, unless you call '''emerge mingw''' manually, have the compiler installed and in your path or alter the environment configuration scripts to add your existing MinGW bin directory to the ''PATH'' variable, compiling anything will choke.  If you run '''emerge mingw''', you will not need to modify the environment configuration scripts to point to a custom location.
    NOTE from a user:
    When I tried to do <tt>emerge qt</tt>, I ended up getting an error  about mingw-make not being in the path, thereby forcing me to do an 'emerge mingw' because of that
    /end note
    If you see an error about ''cc1plus'' not being found, either add MinGW's ''\libexec\gcc\mingw32\3.4.5'' to your ''PATH'' (in command line set PATH=%PATH%;path\to\directory) variable or copy the contents of this directory to MinGW's ''bin'' directory.  The prior is preferred.
    Everything applies to MS Visual Studio Compilers in a similar manner. Note however that for debug builds MS Visual Studio 2005 Service Pack 1 is required due to the use of manifest files and using pre-built packages for some dependecies.
    Under Vista, the mingw directory may need to be moved to c:\ in order to compile properly.
    If you open the command prompt under vista by right clicking and running as administrator, you don't get the UAC issues with vista trying to unsuccesfully run patch as an installer in a seperate environment.


    == Running emerge ==
    == Running emerge ==
    Line 69: Line 64:
      F:\kr>
      F:\kr>


    Check your path (run: <tt>echo %PATH%</tt>), it should have python and various directories within kderoot in it.
    Now you should be able to use emerge. Type
     
    emerge --help
     
    to get some help about it.
     
    == Setting up a compiler ==
    The next step is to tell emerge about a compiler to use. There are three ways to set up a compiler for emerge:
     
    * Let emerge install the MinGW compiler:
     
    To install the MinGW ( "Minimalist GNU for Windows" ) compiler with emerge, type
    emerge mingw
    and wait until it is finished.
     
    * Point emerge to an existing MinGW installation:
     
    <FIXME> This option is not recommended for now, because it only adds one more point of failure, and does not gain something in comparison to the option above.
     
    * Point emerge to an existing Microsoft compiler:
     
    <FIXME>
     
    Currently, there is no dependency on the compilers in any of the packages.  So, unless you call '''emerge mingw''' manually, have the compiler installed and in your path or alter the environment configuration scripts to add your existing MinGW bin directory to the ''PATH'' variable, compiling anything will choke.  If you run '''emerge mingw''', you will not need to modify the environment configuration scripts to point to a custom location.
     
    NOTE from a user:
    When I tried to do <tt>emerge qt</tt>, I ended up getting an error  about mingw-make not being in the path, thereby forcing me to do an 'emerge mingw' because of that
    /end note
     
    If you see an error about ''cc1plus'' not being found, either add MinGW's ''\libexec\gcc\mingw32\3.4.5'' to your ''PATH'' (in command line set PATH=%PATH%;path\to\directory) variable or copy the contents of this directory to MinGW's ''bin'' directory.  The prior is preferred.
     
    Everything applies to MS Visual Studio Compilers in a similar manner. Note however that for debug builds MS Visual Studio 2005 Service Pack 1 is required due to the use of manifest files and using pre-built packages for some dependecies.
     
    Under Vista, the mingw directory may need to be moved to c:\ in order to compile properly.
     
    If you open the command prompt under vista by right clicking and running as administrator, you don't get the UAC issues with vista trying to unsuccesfully run patch as an installer in a seperate environment.
     
     


    * NOTE from a user: be sure that path to \mingw\bin has been set correctly, by default it is pointing to: %KDEROOT%\mingw\bin which does not apply to most installations
    * NOTE from a user: be sure that path to \mingw\bin has been set correctly, by default it is pointing to: %KDEROOT%\mingw\bin which does not apply to most installations

    Revision as of 19:42, 17 February 2008

    emerge is a tool to build the KDE sources and its third party requirements on MS Windows. It is the easy way to build KDE on MS Windows.

    Introduction

    Emerge is a tool that can build the different parts of kde and its dependencies under windows. We created this tool to automate and simplify the build process under windows. We try to build all packages that we offer in the kde installer with emerge. That has some advantages for us:

    • it is easy for people to join us:

    Before emerge it was quite some work to set a system up for development. There were some quirks, which were documented in some mailing lists, but you had to remember them or you ran into an already solved problem again, etc. Now to get a development machine you need a windows computer, need to install python and subversion and do the emerge checkout. Then execute emerge to build what you want to build. This is easy for developers coming from windows to KDE, and also for KDE developers coming to windows.

    • it is easy for us to do (nightly/continuous/release/reproducable/...) builds:

    With emerge you can build the whole software stack (lowlevel libs, qt, kdelibs, things above that) with only one command. You can start that build, and some hours later you can check, if it worked, or if something broke. So we can spot problems easier and earlier. We can also start with a "naked" windows computer without any other installed software and bootstrap kde on it. That ensures, that no hidden dependencies on some pieces of software sneak in, because then the builds on a "naked" computer would break and show the problem.

    • it is easier to collaborate:

    We can test the same emerge build description for a package on different windows versions/computers before we do binary releases. People can also add build descriptions for new packages to the subversion repository.

    This emerge tool was inspired by the Gentoo emerge tool.

    Set up

    Create a directory if possible in your harddrive's root e.g. C:\kderoot or D:\kderoot (You will need this PATH later). This directory will contain the whole kde installation later.

    emerge.bat invokes an emerge.py script written in Python, so you first need to install a Python Interpreter.

    The latest source code for windows emerge and the rest of KDE is stored in a Subversion repository. You need a subversion client for the first checkout. A command line client is available at subversion.tigris.org.

    The sources of emerge are located at the following svn url:

    svn://anonsvn.kde.org/home/kde/trunk/kdesupport/emerge
    

    Check out the sources from the svn-directory of emerge into a new directory, which in this example we will call kderoot. If you have a command-line tool, you can accomplish this with the following command:

    svn co svn://anonsvn.kde.org/home/kde/trunk/kdesupport/emerge
    

    Alternatively, you can checkout the sources using a program like TortoiseSVN.

    Make sure to use a copy of Subversion that was built on Windows so that checked-out files do not use UNIX line endings. If you check out with UNIX line endings, the patch program will fail when attempting to apply a patch whose line endings don't match the system's.

    After checkout you need to have the directory kderoot\emerge. If you don´t, you have to copy your emerge directory to that location.

    Create the directory kderoot\etc. Copy the file kderoot\emerge\kdesettings-example.bat to kderoot\etc\kdesettings.bat and change it according to your needs. Then run it.

    Be sure that you neither have the msys/bin nor the cygwin/bin in your path. If so you have to definitely remove it.

    • NOTE from a user: The applications gimp, inkscape and graphviz are also a problem. To make shure that there goes nothing wrong i stripped my path to contain only what i needed to build.


    Running emerge

    To use emerge you need to start a console window and point that to %KDEROOT%\emerge. For example:

    F:
    cd kderoot\emerge
    

    Then you have to execute kdeenv.bat:

    kdeenv.bat
    

    This tells emerge about your environment settings (pathes, etc.). It will load your configuration from %KDEROOT%\etc\kdesettings.bat. It should not give any errormessages, otherwise emerge will not work as expected. The output should look similar to this one (of course with your paths):

    F:\kr\emerge>kdeenv.bat
    kdesettings.bat executed
    KDEROOT     : f:\kr
    KDECOMPILER : mingw
    KDESVNDIR   : f:\kdesvn
    PYTHONPATH  : f:\python25
    DOWNLOADDIR : f:\kdl
    
    F:\kr>
    

    Now you should be able to use emerge. Type

    emerge --help
    

    to get some help about it.

    Setting up a compiler

    The next step is to tell emerge about a compiler to use. There are three ways to set up a compiler for emerge:

    • Let emerge install the MinGW compiler:

    To install the MinGW ( "Minimalist GNU for Windows" ) compiler with emerge, type

    emerge mingw
    

    and wait until it is finished.

    • Point emerge to an existing MinGW installation:

    <FIXME> This option is not recommended for now, because it only adds one more point of failure, and does not gain something in comparison to the option above.

    • Point emerge to an existing Microsoft compiler:

    <FIXME>

    Currently, there is no dependency on the compilers in any of the packages. So, unless you call emerge mingw manually, have the compiler installed and in your path or alter the environment configuration scripts to add your existing MinGW bin directory to the PATH variable, compiling anything will choke. If you run emerge mingw, you will not need to modify the environment configuration scripts to point to a custom location.

    NOTE from a user: When I tried to do emerge qt, I ended up getting an error about mingw-make not being in the path, thereby forcing me to do an 'emerge mingw' because of that /end note

    If you see an error about cc1plus not being found, either add MinGW's \libexec\gcc\mingw32\3.4.5 to your PATH (in command line set PATH=%PATH%;path\to\directory) variable or copy the contents of this directory to MinGW's bin directory. The prior is preferred.

    Everything applies to MS Visual Studio Compilers in a similar manner. Note however that for debug builds MS Visual Studio 2005 Service Pack 1 is required due to the use of manifest files and using pre-built packages for some dependecies.

    Under Vista, the mingw directory may need to be moved to c:\ in order to compile properly.

    If you open the command prompt under vista by right clicking and running as administrator, you don't get the UAC issues with vista trying to unsuccesfully run patch as an installer in a seperate environment.


    • NOTE from a user: be sure that path to \mingw\bin has been set correctly, by default it is pointing to: %KDEROOT%\mingw\bin which does not apply to most installations

    You can get 'some' help if you run:

    C:\kderoot\emerge\bin>emerge --help
    

    Below the directory kderoot\emerge\portage are subdirectories for categories as subdirectories which contain the instructions for individual packages. The emerge script automatically handles package dependencies (except for the compiler, see #Compiling).

    To build every required package for e.g. kdebase enter emerge kdebase. If you want to make a dry run, add the option -p to it.

    Start with emerge qt and if that completes successfully, run emerge [TARGET] where [TARGET] has to be replaced with the target you want to build. You can specify multiple targets in within a single command.

    What emerge does

    emerge will fetch Windows versions of numerous UNIX-like utilities and libraries from the Internet, putting them in kderoot\bin, then get the Win32 support files, then Subversion, then Perl and the Qt libraries, etc.

    Then emerge compiles the Qt libraries, this takes hours.

    emerge package performs the separate actions --fetch, --unpack, --compile, --install, --manifest, and --qmerge.

    emerge commandline options and settings

    There are some options that can be used when building with emerge.

    -v EMERGE_VERBOSE This option augments the verbosity level - currently the highest verbosity level is 3 (-v -v -v). A verbosity level of 0 should give no output and equals to -q. You can set EMERGE_VERBOSE=3 instead in the environment of the commandline or within your kdesettings.bat file.
    --nocopy EMERGE_NOCOPY This very useful option suppresses copying the sources from the local subversion tree to a directory within the build directory. It shouldn't be used while packaging; in the other cases it reduces the amount of harddisk used though and removes the copying time.You can set EMERGE_NOCOPY=True or =False instead.
    --offline This option suppresses the update step of the local tree - which needs some time. Be aware though that you have to have existing sources already if you want to use this option.
    -t EMERGE_BUILDTESTS This option enables or disables KDE4 buildtests for KDE modules. Other packages will not change. Use EMERGE_BUILDTESTS=True or =False.
    --buildtype= Debug This option enables full debugging for the build. Recommended if you plan to debug the runtime or provide more valuable feedback to developers about software defects. You can also change the 'set EMERGE_BUILDTYPE=RelWithDebInfo' line in the kdesettings.bat file.

    Hints

    • Once you have packagename built, type emerge --unmerge packagename --noclean --target=svnHEAD packagename to update packagename from the subversion and compile it without removing the build dir.

    Notes

    emerge can mostly cooperate with the kdewin-installer but we're currently still working on some packages which are packaged in a wrong way. It is not recommended to use another layout then installer for directory_layout in the kdesettings.bat anymore (see that file for more detailed information).

    emerge creates lots of files in \kderoot\tmp during build. After a package is successfully installed (check \kderoot\etc\portage\installed or the directory \kderoot\manifest\), you can delete its temporary directory.

    Windows emerge is derived from the Gentoo portage system, but we are currently not enforcing compatibility. If you have questions about that please contact us at the channel #kde-windows on irc.freenode.net.

    Vista issues

    • jstaniek 12:02, 15 January 2008 (CET): UAC has infamous heuristics that make programs like patch.exe treat as installers and try to run them with admin rights (!). This heuristics can be tricked by renaming patch.exe to something like pch.exe (example) but we did not want to add item to our infrastructure. Instead it is possibleto turn off the heuristics (see the screenshot here in the security blog calling the heuristics 'severe hole in the design of UAC'). If you happen to disable the UAC, as many annoyed users and devs do (msvc demands admin rights anyway!), patch.exe should already work for you as in older Windows. Alternatively you may want to disable UAC for admins only, but this makes no sense if you are the only user of your machine and use only the admin account.