1Date: 28-Feb-2007 2Update: 19-Feb-2015 3Author: Nicola Pero <nicola.pero@meta-innovation.com> 4 after Richard Frith-Macdonald <rfm@gnu.org>, 5 Germán Arias <germanandre@gmx.es> and others. 6 7 8PURPOSE 9------- 10 11This document is intended to provide a step by step instruction on how 12to use GNUstep on recent Windows operating systems. 13 14It will get as far as explaining how to build a GNUstep application 15and create a standalone version that can be shipped standalone to 16Windows end users. 17 18The recommended way to get GNUstep working on Windows is to use MinGW 19and MSYS to get a Unix-like environment where you can easily build 20your GNUstep software (this is what is described in this file). 21 22Software built in the MinGW/MSYS environment is native Windows 23software that you can then run without having to rely on the environment 24you used to build. 25 26So, this document is divided in two parts. 27 28In the first part ("STEP BY STEP INSTALLATION INSTRUCTIONS"), we will 29describe how to get MinGW/MSYS up and running, and how to build 30GNUstep software in this environment. 31 32In the second part ("HOW TO SHIP YOUR GNUSTEP APPLICATION TO WINDOWS 33USERS"), we'll show an example of how to package (and use) the .exes, 34.dlls and resources (that you can build using the environment 35described in the first part) as Windows standalone binaries. 36 37 38INTRODUCTION TO MINGW 39--------------------- 40 41MinGW is a collection of header files and import libraries that allow 42one to use GCC and produce native Windows32 programs that do not rely 43on any 3rd-party DLLs. 44 45MSYS is a very much cut down version of the Cygwin environment ... 46providing a minimal set of tools needed to build programs using 47MingGW. If you wish to build for MinGW by cross-compiling from a 48Cygwin environment, please read README.Cygwin instead. 49 50 51PRELIMINARIES 52------------- 53 54One way to vastly simplify installing GNUstep, is to use the Windows-based 55GNUstep installer. Get it from: 56 57http://www.gnustep.org/windows/installer.html 58 59If you have already installed this, you can skip to the end and just 60start compiling and packaging applications! Although you may want to 61read the rest of the instructions for other helpful information. 62 63 64 65A. STEP BY STEP INSTALLATION INSTRUCTIONS 66----------------------------------------- 67 681. Install MinGW 69================ 70 71Download MinGW-Get-Setup.exe from 72 73 http://sourceforge.net/projects/mingw/files/Installer/ 74 75Then start it up. Set the installation path to 76 77C:\xxx\ 78 79Where \xxx\ is the top-level path you want to use, I use Nicola/GNUstep so 80I install it into C:\Nicola\GNUstep\. We will refer to this path as MINGWPATH. 81 82 832. Install necessary packages 84============================= 85 86MinGW create an access on the desktop to the "MinGW installer", a package 87manager you can use to install packages available to MinGW. To build GNUstep 88you will need many packages. 89 90At MinGW Installer select "All packages" and then install the following 91packages (bin and dev packages when correspond): 92 93(I'm really not sure if all them are necessary) 94 95mingw32-autoconf 96mingw32-binutils 97mingw32-bzip2 98mingw32-gcc 99mingw32-gcc-g++ 100mingw32-gcc-objc 101mingw32-gdb 102mingw32-gmp 103mingw32-libbz2 104mingw32-libgmp 105mingw32-libiconv 106mingw32-libintl 107mingw32-libpthread-old 108mingw32-libpthreadgc 109mingw32-libtool 110mingw32-libunistring 111mingw32-libz 112mingw32-make 113mingw32-pkginfo 114mingw32-pthreads-w32 115mingw32-w32api 116msys-base 117msys-bash 118msys-console 119msys-crypt 120msys-diffutils 121msys-libcrypt 122msys-libgmp 123msys-libiconv 124msys-libminires 125msys-m4 126msys-minires 127msys-zlib 128 129 1303. Additional Useful Tools 131========================== 132 133You will need install GNUstep from Subversion, so you need a Subversion 134client. I used: 135 136http://www.sliksvn.com/pub/Slik-Subversion-1.6.9-win32.msi 137 138and then install subversion in a random directory. 139 140 141You will need and editor, for example Emacs. Get a Windows version for 142MinGW from: 143 144https://www.gnu.org/software/emacs/ 145 146To install it, simply unpack it in your MINGWPATH, you can now 147execute the binary in 'MINGWPATH/bin'. 148 149 1503. Additional Windows steps 151=========================== 152 153You may need to edit /MINGWPATH/include/winsock2.h to change the size of the 154sa_data field in the sockaddr structure from 14 to 22 ... this is because 155some versions of Windows have changed the layout of this structure. 156This modification may be needed to be able to correctly determine the 157network interface details for your machine. 158 159 160On Windows Vista and later, an additional problem has been reported 161where 'make install' would sometimes fail because of permission 162problems. The problem is discussed here -- 163 164http://lists.gnu.org/archive/html/gnustep-dev/2010-06/msg00055.html 165 166you may have to install the additional MinGW files, as explained 167there. 168 169 1704. Mount your MINGWPATH directory 171================================= 172 173With Emacs create a file called "fstab" in C:\MINGWPATH\msys\x.x\etc and add 174a line like: 175 176 C:\MINGWPATH /mingw 177 178Remember MINGWPATH is the path where you installed mingw (We assume you 179install it at your C: drive, if not change it). "mingw" is the name to 180refer to your MINGWPATH directory inside MSYS console, you can use any other 181name, but remember it because we will need this later. We will refer to this 182name as MOUNTDIR. 183 184 1855. Launch the MSYS console 186========================== 187 188Launch the console at C:\MINGWPATH\msys\x.x\msys.bat (double click). 189 190 1916. Installing gnustep-make 192========================== 193 194Get gnustep-make: 195 196svn co http://svn.gna.org/svn/gnustep/tools/make/trunk make 197 198Then install it (avoid warning about conftest.exe): 199 200cd make 201./configure 202make 203make install 204 205 2067. Special recommendation 207========================= 208 209In next steps don't use "make -j", because can cause problems. 210 211 2128. Installing libffi 213==================== 214 215Download libffi-x.x.x.tar.gz from https://sourceware.org/libffi/. 216Unpack it, compile and install: 217 218cd libffi-x.x.x 219./configure --prefix=/MOUNTDIR 220make 221make install 222mv /MOUNTDIR/lib/libffi-x.x.x/include/* /MOUNTDIR/include/ 223 224(if you get a popup about contest.exe failing, just ignore it) 225NB. The headers have to be moved manually because the package won't install 226them in the right place. 227 228 2299. Install ICU 230============== 231 232Download latest ICU from http://site.icu-project.org/ (zip package). 233Unpack it, compile and install as fallow: 234 235cd icu/source 236./runConfigureICU --disable-release MinGW --prefix=/MOUNTDIR 237make 238make install 239 240 24110. Install GNUtls 242================== 243 244Download the latest version from the official page (windows binary). Copy 245this at your MINGWPATH directory and unpack it. 246 247 24811. Install pkg-config 249====================== 250 251The best option is install pkg-config lite from: 252 253http://sourceforge.net/projects/pkgconfiglite/files/ 254 255Download latest version, unpack it an copy the files at corresponding 256directories in your MINGWPATH directory. 257 258 25912. Install xml2 260================ 261 262There are available binary packages of xml, but all these don't provide an 263m4 file to be used with pkg-config. And since gnustep-base use pkg-config to 264detect xml we need install it from source. So download the latest version 265from http://xmlsoft.org/ and install it: 266 267cd libxml2-x.x.x 268./configure --prefix=/MOUNTDIR 269make 270make install 271 272 27313. Fix problem with mingwrt 274============================ 275 276(I you are using mingw32-mingwrt-3.21.1 or above skip this step. 277Run MinGW Installer to see what version are you using.) 278 279Launch Emacs and open the file /MINGWPATH/include/unistd.h 280 281And comment the line 95 (#include <parts/time.h>) and all the function 282nanosleep (from line 104 to 117). Save the file. 283 284 28514. Source GNUstep.sh 286===================== 287 288Probably you will need source the GNUstep script: 289 290. /local/share/GNUstep/Makefiles/GNUstep.sh 291 292 29315. Install gnnustep-base 294========================= 295 296Get gnustep-base: 297 298svn co http://svn.gna.org/svn/gnustep/libs/base/trunk base 299 300Then compile and install it: 301 302cd base 303./configure 304make 305make install 306 307 30816. Install jpeg 309================ 310 311Download the latest version from http://ijg.org/. Then compile and install it 312as fallow: 313 314cd jpeg-xx 315autoheader 316./configure --prefix=/MOUNTDIR 317make 318make install 319 320 32117. Install libtiff 322=================== 323 324Download latest version from http://www.libtiff.org/. Then compile and 325install it: 326 327cd tiff-x.x.x 328./configure --prefix=/MOUNTDIR 329make 330make install 331 332 33318. Install libpng 334================== 335 336Download latest version from http://libpng.org/pub/png/libpng.html. 337Then compile and install it: 338 339cd lpngXXX 340cp scripts/pnglibconf.h.prebuild pnglibconf.h 341cp scripts/makefile.msys makefile 342 343Launch Emacs and edit the makefile to set prefix as "prefix=/MOUNTDIR", then: 344 345make 346make install 347 348 34919. Install libungif 350==================== 351 352From http://gnuwin32.sourceforge.net/ download 353 354 libungif-4.1.4-1.exe 355 356Execute it and install the package into your MINGWPATH directory. 357 358 35920. Install libao 360================= 361 362Download libao from http://xiph.org/ao/. And install it: 363 364cd libao-x.x.x 365./cofigure --prefix=/MOUNTDIR 366make 367make install 368 369 37021. Install Aspell 371================== 372 373Download the windows port http://aspell.net/win32/. And 374install it in your MINGWPATH directory (directly in your MINGWPATH directory, 375not under the Aspell directory). 376 377Download also the dev package, unpack it and copy the libraries and headers 378to the corresponding directories at your MINWGPATH directory. 379 380Download also the installers for the dictionaries you want use, extract and 381install them into your MINGWPATH directory (directly in your MINGWPATH 382directory, not under the Aspell directory). 383 384Now you need change the name of some libraries, go to directory MINGWPATH/lib 385and change the name of these files: 386 387aspell-15.def ----> aspell.def 388aspell-15.lib ----> aspell.lib 389libaspell-15-dll.lib ----> libaspell-dll.lib 390 391 39222. Add path to icu libraries 393============================= 394 395FIXME: Why this is needed? 396 397Edit the file /MINGWPATH/msys/etc/profile and add the path to ICU libs: 398 399export PATH=$PATH:/MOUNTDIR/lib 400 401 40223. Install gnustep-gui 403======================= 404 405Get gnustep-gui: 406 407svn co http://svn.gna.org/svn/gnustep/libs/gui/trunk gui 408 409Then compile and install it: 410 411cd gui 412./configure 413make 414make install 415 416 41724. Install gnustep-back 418======================== 419 420Get gnustep-back: 421 422svn co http://svn.gna.org/svn/gnustep/libs/back/trunk back 423 424Then compile and install it: 425 426cd back 427./configure 428make 429make install 430 431 43225. Install gnustep-back with cairo graphics (optional but highly recommended) 433============================================================================== 434 435Download fallowing packages: 436 437http://ftp.gnome.org/pub/gnome/binaries/win32/dependencies/cairo_1.10.2-2_win32.zip 438http://ftp.gnome.org/pub/gnome/binaries/win32/dependencies/cairo-dev_1.10.2-2_win32.zip 439http://ftp.gnome.org/pub/gnome/binaries/win32/dependencies/libpng_1.4.3-1_win32.zip 440http://ftp.gnome.org/pub/gnome/binaries/win32/dependencies/freetype_2.4.2-1_win32.zip 441http://ftp.gnome.org/pub/gnome/binaries/win32/dependencies/freetype-dev_2.4.2-1_win32.zip 442http://ftp.gnome.org/pub/gnome/binaries/win32/dependencies/fontconfig_2.8.0-2_win32.zip 443http://ftp.gnome.org/pub/gnome/binaries/win32/dependencies/fontconfig-dev_2.8.0-2_win32.zip 444 445 446Copy these packages at your MINGWPATH directory and unpack them. Now move some 447headers: 448 449mv /MOUNTDIR/include/cairo/* /MOUNTDIR/include/ 450mv /MOUNTDIR/include/freetype2/freetype/ /MOUNTDIR/include/ 451 452Now we need recompile gnustep-back to use cairo backend: 453 454cd back 455make distclean 456./configure --enable-graphics=cairo --with-name=cairo LIBS=-lcairo 457make 458make install 459 460Now set defaults to use this backend: 461 462defaults write NSGlobalDomain GSBackend cairo 463 464 46526. Install WinUXTheme (optional) 466================================= 467 468Get WinUXTheme: 469 470svn co http://svn.gna.org/svn/gnustep/plugins/themes/WinUXTheme/ winuxtheme 471 472Then compile and install it: 473 474cd winuxtheme 475make 476make install 477 478Set it: 479 480defaults write NSGlobalDomain GSTheme WinUXTheme 481 482 48327. Source the gnustep script when launch the console 484===================================================== 485 486Edit the file /MINGWPATH/msys/etc/x.x/profile and add this line to source the 487gnustep script: 488 489. /local/share/GNUstep/Makefiles/GNUstep.sh 490 491 49228. Set up the spell chequer service 493==================================== 494 495The spell chequer service need be configured. So we need launch it once 496to configure it. Run the command: 497 498/local/lib/GNUstep/Services/GSspell.service/GSspell.exe 499 500 50129. Testing your gui installation 502================================= 503 504Get the examples: 505 506svn co http://svn.gna.org/svn/gnustep/tests/examples/trunk/ examples 507 508Go in a simple gui application (examples/gui a very good starting 509point), compile and run it. :-). Ink and PowerPaint should work fine 510on Windows, test these. 511 512Additionally, you might want to compile and run Gorm or other GNUstep 513applications. Gorm (and hopefully other GNUstep applications too) 514should compile and run out of the box. 515 516 517Troubleshooting 518--------------- 519 520Issues with updating: 521Before attempting to update your GNUstep installation, be sure to stop/kill 522all running GNUstep programs or services (i.e. gdomap, gdnc, gpbs) since 523Windows cannot overwrite files that are currently in use. 524 525Where we specify specific versions of packages to be used, we have 526tested with those versions - later or earlier versions may work, but 527may well not. Generally earlier versions should be assumed not to 528work. 529 530 531 532B. HOW TO SHIP YOUR GNUSTEP APPLICATION TO WINDOWS USERS 533-------------------------------------------------------- 534 535You probably want to ship your Windows application as a standalone 536.zip file that Windows users can easily download and use. 537 538We will explain what to do with an example: that of packaging 539Gomoku.app. We will first build the application (creating 540Gomoku.app), then we'll add to to it all the GNUstep DLLs and 541resources that are needed to run the application, and we'll end up 542with a single directory, Gomoku.app, that contains a program 543(Gomoku.exe) and a bunch of DLLs and various other resources required 544to run the program. 545 546The end user just needs to get this directory (from a .zip or .tgz 547file, for example) and can double-click on Gomoku.exe to start the 548program (no GNUstep installation required). 549 550 5511. Build the application 552======================== 553 554Build your application (Gomoku.app in this example) in your 555MinGW/GNUstep environment. Generally, this means getting the source 556code and typing 'make' in it. If you're trying to follow the 557Gomoku.app example, the source code is here: 558 559http://www.gnustep.it/nicola/Applications/Gomoku/index.html 560 561Once you have built it, make sure you can run your application from 562within mingw by using 'openapp', as in 'openapp ./Gomoku.app'. 563 5642. Copy your application somewhere 565================================== 566 567Now take your built application and copy it somewhere -- we'll be 568working on it! Eg, I just copy it in my home directory. 569 570cp -R /home/Nico/Gomoku-1.2.8/Gomoku.app /home/Nico/ 571 572 5733. Copy DLLs into your application 574================================== 575 576Now search for MinGW/GNUstep DLL files in /MOUNTDIR/bin, /MOUNTDIR/lib and 577/local/bin, and copy them all into Gomoku.app: 578 579cp $(find /MOUNTDIR/bin -name *.dll) /home/Nico/Gomoku.app/ 580cp $(find /MOUNTDIR/lib -name *.dll) /home/Nico/Gomoku.app/ 581cp $(find /local/bin -name *.dll) /home/Nico/Gomoku.app/ 582 583 5844. Copy config files into your application 585========================================== 586 587Now copy the "etc" directory in /MOUNTDIR to Gomoku.app: 588 589cp -R /MOUNTDIR/etc /home/Nico/Gomoku.app/ 590 591 5925. Copy your GNUstep Library folder 593=================================== 594 595Now copy all of the GNUstep resources into the application -- 596 597mkdir -p /home/Nicola/Gomoku.app/GNUstep/ 598cp -R /local/lib/GNUstep/* /home/Nico/Gomoku.app/GNUstep/ 599 600I put them all into Gomoku.app/GNUstep/, which means that later on 601I'll set up the GNUstep.conf file to map GNUSTEP_*_LIBRARY to that 602directory. 603 604 6056. Copy key GNUstep binary programs 606=================================== 607 608cp /local/bin/gpbs.exe /home/Nicola/Gomoku.app 609cp /local/bin/gdnc.exe /home/Nicola/Gomoku.app 610cp /local/bin/gdomap.exe /home/Nicola/Gomoku.app 611cp /local/bin/make_services.exe /home/Nicola/Gomoku.app 612cp /local/bin/defaults.exe /home/Nicola/Gomoku.app 613 614I put them all into Gomoku.app, which means that later 615on I'll set up the GNUstep.conf file to map GNUSTEP_*_TOOLS to that 616directory. 617 618 6197. Add a GNUstep.conf 620===================== 621 622You need to add a Gomoku.app/GNUstep.conf file to tell gnustep-base 623where to find things inside Gomoku.app -- here is the one I use (which 624matches the locations where I copied things in the previous steps) -- 625 626GNUSTEP_USER_CONFIG_FILE=.GNUstep.conf 627GNUSTEP_USER_DIR=GNUstep 628GNUSTEP_USER_DEFAULTS_DIR=GNUstep/Defaults 629 630GNUSTEP_SYSTEM_APPS=./GNUstep/Apps 631GNUSTEP_SYSTEM_ADMIN_APPS=./GNUstep/Apps 632GNUSTEP_SYSTEM_TOOLS=./ 633GNUSTEP_SYSTEM_ADMIN_TOOLS=./ 634GNUSTEP_SYSTEM_LIBRARY=./GNUstep 635GNUSTEP_SYSTEM_HEADERS=./GNUstep/Headers 636GNUSTEP_SYSTEM_LIBRARIES=./GNUstep/Libraries 637GNUSTEP_SYSTEM_DOC=./GNUstep/Documentation 638GNUSTEP_SYSTEM_DOC_MAN=./GNUstep/Documentation/man 639GNUSTEP_SYSTEM_DOC_INFO=./GNUstep/Documentation/info 640 641GNUSTEP_NETWORK_APPS=./GNUstep/Apps 642GNUSTEP_NETWORK_ADMIN_APPS=./GNUstep/Apps 643GNUSTEP_NETWORK_TOOLS=./ 644GNUSTEP_NETWORK_ADMIN_TOOLS=./ 645GNUSTEP_NETWORK_LIBRARY=./GNUstep 646GNUSTEP_NETWORK_HEADERS=./GNUstep/Headers 647GNUSTEP_NETWORK_LIBRARIES=./GNUstep/Libraries 648GNUSTEP_NETWORK_DOC=./GNUstep/Documentation 649GNUSTEP_NETWORK_DOC_MAN=./GNUstep/Documentation/man 650GNUSTEP_NETWORK_DOC_INFO=./GNUstep/Documentation/info 651 652GNUSTEP_LOCAL_APPS=./GNUstep/Apps 653GNUSTEP_LOCAL_ADMIN_APPS=./GNUstep/Apps 654GNUSTEP_LOCAL_TOOLS=./ 655GNUSTEP_LOCAL_ADMIN_TOOLS=./ 656GNUSTEP_LOCAL_LIBRARY=./GNUstep 657GNUSTEP_LOCAL_HEADERS=./GNUstep/Headers 658GNUSTEP_LOCAL_LIBRARIES=./GNUstep/Libraries 659GNUSTEP_LOCAL_DOC=./GNUstep/Documentation 660GNUSTEP_LOCAL_DOC_MAN=./GNUstep/Documentation/man 661GNUSTEP_LOCAL_DOC_INFO=./GNUstep/Documentation/info 662 663So, just copy and paste this code into a GNUstep.conf file that you 664put into /home/Nico/Gomoku.app/GNUstep.conf. 665 666 6678. Add a GlobalDefaults.plist 668============================= 669 670You need to add a Gomoku.app/GlobalDefaults.plist file to tell GNUstep 671the defaults you want use (the theme, backend, etc.), and save this file 672with write/read permission only for the owner (chmod 600). For example: 673 674<?xml version="1.0" encoding="UTF-8"?> 675<!DOCTYPE plist PUBLIC "-//GNUstep//DTD plist 0.9//EN" "http://www.gnustep.org/plist-0_9.xml"> 676<plist version="0.9"> 677 <dict> 678 <key>GSTheme</key> 679 <string>WinUXTheme</string> 680 <key>GSBackend</key> 681 <string>cairo</string> 682 </dict> 683</plist> 684 685 6868. Now the application should be working 687======================================== 688 689At this stage, everything should be working "standalone". 690 691By that we mean that if you give your Gomoku.app/ to a Windows user 692(with no GNUstep installed on their machine), they should be able to 693run it by just double-clicking on the Gomoku executable inside of the 694Gomoku.app/ directory! :-) 695 696Try it out and make sure that it works. 697 698 6999. Cleanup 700========== 701 702If you look at your Gomoku.app/ directory, you will see that it is 703really big. We mass-copied stuff from the GNUstep/MinGW directories; 704but generally, you want to make sure you remove anything that you 705don't strictly need. So go in there and remove anything that you 706don't need. 707 708First thing, you should remove the MSYS libraries, which we never use -- 709 710rm Gomoku.app/msys-1.0.dll 711rm Gomoku.app/msysltdl-3.dll 712rm Gomoku.app/libW11.dll 713rm Gomoku.app/libperl.dll 714rm Gomoku.app/librle3.dll 715 716Then, remove any additional library that your application doesn't use; 717for example, I removed -- 718 719rm Gomoku.app/Renaissance.dll 720rm Gomoku.app/ProjectCenter.dll 721 722Finally, remove Apps and other stuff that you might have copied from 723the general GNUstep installation -- 724 725rm -Rf Gomoku.app/GNUstep/Apps 726rm -Rf Gomoku.app/GNUstep/Frameworks/ProjectCenter.framework 727 728Generally, you may want to build the whole stuff making sure you only 729include what you strictly need. 730 731 73210. Stripping 733============= 734 735The resulting directory might still be pretty big. If you are trying 736to distribute it over the internet, your users will probably 737appreciate if you stripped it, removing symbols. Just run 'strip' 738on all the .exe and .dll files in your application. 739 740strip $(find /home/Nico/Gomoku.app/ -name '*.exe') 741strip $(find /home/Nico/Gomoku.app/ -name '*.dll') 742 743That will reduce the size a lot. If you're not distributing it over 744the internet, you might be happy leaving the symbols in though. 745 746 74711. Checking Licenses 748==================== 749 750Finally, before deployment, you need to realize that you are shipping 751a lot of GNUstep (and non-GNUstep) software with your application. 752 753This is fine, just make sure you are aware of the licenses, and that 754you comply with them. 755 756 757PACKAGING/WINDOWS TODOS 758----------------------- 759 760The gdnc, gpbs processes are somehow a bit of a pain. They are 761automatically started when you start your application, but they are 762not automatically stopped when you quit it. This might have bad 763consequences, eg, if you are using your application from a USB flash 764disk, Windows doesn't let you unplug the USB disk while gdnc/gpbs are 765running, because they are running from the disk! 766 767Also, it's not clear what happens if you have two or three such 768GNUstep apps downloaded from the web and you try to run them at the 769same time. What about gdomap etc ? 770