diff options
Diffstat (limited to 'README.win32')
| -rw-r--r-- | README.win32 | 749 |
1 files changed, 749 insertions, 0 deletions
diff --git a/README.win32 b/README.win32 new file mode 100644 index 0000000000..a6d2609aae --- /dev/null +++ b/README.win32 @@ -0,0 +1,749 @@ +How to build Erlang/OTP on Windows. +----------------------------------- +Table of contents + +1. Introduction +2. Answers to some "frequently asked questions" +3. Tools you need and their environment +4. The shell environment +5. Building and installing +6. Development +7. Final words + +%CopyrightBegin% + +Copyright Ericsson AB 2003-2009. All Rights Reserved. + +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +%CopyrightEnd% + + + +Introduction +------------ + +This file describes how to build the Erlang emulator and the OTP +libraries on Windows. The instructions apply to versions of Windows +supporting the Cygwin emulated gnuish environment for Windows. We've +built on the following platforms: Windows 2000 Professional, Windows +2003 server, Windows XP Home/Professional, and Windows Vista. Any +Windows95'ish platform will surely get you into trouble, what I'm not +sure of, but it certainly will... + +The procedure described uses Cygwin as a build environment, you run +the bash shell in Cygwin and uses gnu make/configure/autoconf etc to +do the build. The emulator C-source code is, however, mostly compiled +with Microsoft Visual C++(tm), producing a native Windows binary. This +is the same procedure as we use to build the pre-built binaries. The +fact that we use VC++ and not gcc is explained further in the FAQ +section. + +I describe the build procedure to make it possible for open source +customers to build the emulator, given that they have the needed +tools. The binary Windows releases is still a preferred alternative if +one does not have Microsoft's development tools and/or don't want to +install Cygwin. + +To use Cygwin, one needs basic experience from a Unix environment, if +one does not know how to set environment variables, run programs etc +in a Unix environment, one will be quite lost in the Cygwin +ditto. I can unfortunately not teach all the world how to use +Cygwin and bash, neither how to install Cygwin nor perform basic tasks +on a computer. Please refer to other documentation on the net for +help, or use the binary release instead if you have problems using the +tools. + +However, if you feel comfortable with the environment and build +system, and have all the necessary tools, you have a great opportunity +to make the Erlang/OTP distribution for Windows better. Please submit +any suggestions and patches to the appropriate mailing lists (see +http://www.erlang.org) to let them find their way into the next +version of Erlang. If making changes to the build system (like +makefiles etc) please bear in mind that the same makefiles are used on +Unix/VxWorks/OSEDelta, so that your changes don't break other +platforms. That of course goes for C-code too, system specific code +resides in the $ERL_TOP/erts/emulator/sys/win32 and $ERL_TOP/erts/etc/win32 +directories mostly. The $ERL_TOP/erts/emulator/beam directory is for +common code. + +Before the R9C release of Erlang/OTP, the Windows release was built +partly on a Unix (Solaris) box and partly on a Windows box, using Perl +hacks to communicate and sync between the two machines. R9C was the +first release ever built solely on Windows, where no Unix machine is +needed at all. Now we've used this build procedure for a couple of +releases, and it has worked fine for us. Still, there might be all +sorts of troubles on different machines and with different +setups. I'll try to give hints wherever I've encountered difficulties, +but please share your experiences by using the mailing list [email protected]. I cannot of course help everyone with all +their problems, please try to solve the problems and submit +solutions/workarounds. Remember, it's all about sharing, not about +demanding... + +Lets go then, I'll start with a little FAQ, based on in house questions +and misunderstandings. + + +Answers to "frequently asked questions" +--------------------------------------- + +Q: So, now I can build Erlang using GCC on Windows? + +A: No, unfortunately not. You'll need Microsoft's Visual C++ still, a +Bourne-shell script (cc.sh) wraps the Visual C++ compiler and runs it +from within the Cygwin environment. All other tools needed to build +Erlang are free-ware/open source, but not the C compiler. + +Q: Why haven't you got rid of VC++ then, you ****** + +A: Well, partly because it's a good compiler - really! Actually it's +been possible in late R11-releases to build using mingw instead of +visual C++ (you might see the remnants of that in some scripts and +directories). Unfortunately the development of the SMP version for +Windows broke the mingw build and we chose to focus on the VC++ build +as the performance has been much better in the VC++ versions. The +mingw build will be back, but as long as VC++ gives better +performance, the commercial build will be a VC++ one. + +Q: OK, VC++ you need, but now you've started to demand a very recent +(and expensive) version of Visual studio, not the old and stable VC++ +6.0 that was used in earlier versions. Why? + +A: The SMP version of Erlang needs features in the Visual Studio +2005. Can't live without them. Besides the new compiler gives the +Erlang emulator a ~40% performance boost(!) + +Q: Can/will I build a Cygwin binary with the procedure you describe? + +A: No, the result will be a pure Windows binary, and as far as I know, +it's not possible to make a Cygwin binary yet. That is of course +something desirable, but there are still some problems with the +dynamic linking (dynamic Erlang driver loading) as well as the TCP/IP +emulation in Cygwin, which, I'm sure of, will improve, but still has +some problems. Fixing those problems might be easy or might be hard. +I suggest you try yourself and share your experience. No one would be +happier if a simple ./configure && make would produce a fully fledged +Cygwin binary. Ericsson does however not pay me to do a Cygwin port, so +such a port would have to happen in spare time, which is a limited resource... + +Q: Hah, I saw you, you used GCC even though you said you didn't! + +A: OK, I admit, one of the files is compiled using Cygwin's GCC and +the resulting object code is then converted to MS VC++ compatible coff +using a small C hack. It's because that particular file, beam_emu.c +benefits immensely from being able to use the GCC labels-as-values +extension, which boosts emulator performance by up to 50%. That does +unfortunately not (yet) mean that all of OTP could be compiled using +GCC, that particular source code does not do anything system specific +and actually is adopted to the fact that GCC is used to compile it on +Windows. + +Q: So now there's a MS VC++ project file somewhere and I can build OTP +using the nifty VC++ GUI! + +A: No, never. The hassle of keeping the project files up to date and +do all the steps that constitute an OTP build from within the VC++ GUI +is simply not worth it, maybe even impossible. A VC++ project +file for Erlang/OTP will never happen, at least I will never make +one. Clicking around in super-multi-tab'd dialogs to add a file or +compiler option when it's so much easier in a makefile is simply not +my style. + +Q: So how does it all work then? + +A: Cygwin is the environment, which closely resembles the environments +found on any Unix machine. It's almost like you had a virtual Unix +machine inside Windows. Configure, given certain parameters, then +creates makefiles that are used by the Cygwin gnu-make to built the +system. Most of the actual compilers etc are not, however, Cygwin +tools, so I've written a couple of wrappers (Bourne-shell scripts), +which reside in $ERL_TOP/etc/win32/cygwin_tools and they all do +conversion of parameters and switches common in the Unix environment +to fit the native Windows tools. Most notable is of course the paths, +which in Cygwin are Unix-like paths with "forward slashes" (/) and no +drive letters, the Cygwin specific command 'cygpath' is used for most +of the path conversions. Luckily most compilers accept forward slashes +instead of backslashes as path separators, one still have to get the +drive letters etc right, though. The wrapper scripts are not general +in the sense that, for example, cc.sh would understand and translates +every possible gcc option and passes correct options to cl.exe. The +principle is that the scripts are powerful enough to allow building of +Erlang/OTP, no more, no less. They might need extensions to cope with +changes during the development of Erlang, that's one of the reasons I +made them into shell-scripts and not Perl-scripts, I believe they are +easier to understand and change that way. I might be wrong though, +cause another reason I didn't write them in Perl is because I've never +liked Perl and my Perl code is no pleasant reading... + +In $ERL_TOP, there is a script called otp_build, that script handles +the hassle of giving all the right parameters to configure/make and +also helps you set up the correct environment variables to work with +the Erlang source under Cygwin. + +Q: You use and need Cygwin, but then you haven't taken the time to +port Erlang to the Cygwin environment but instead focus on your +commercial release, is that really ethical? + +A: No, not really, but see this as a step in the right direction. I'm +aiming at GCC compiled emulators and a Cygwin version, but I really +need to do other things as well... In time, but don't hold your +breath... + +Q: Can I build something that looks exactly as the commercial release. + +A: Yes, we use the exactly same build procedure. + +Q: Which version of Cygwin and other tools do you use then? + +A: For Cygwin we try to use the latest releases available when +building. What versions you use shouldn't really matter, I try to +include workarounds for the bugs I've found in different Cygwin +releases, please help me to add workarounds for new Cygwin-related +bugs as soon as you encounter them. Also please do submit bug reports +to the appropriate Cygwin developers. The Cygwin GCC we used for R13B +was version 3.4.4. We used VC++ 8.0 (i.e. Visual studio 2005 SP1), +Sun's JDK 1.5.0_17, NSIS 2.37, and Win32 OpenSSL 0.9.8e. Please read +the next section for details on what you need. + +Q: Can you help me setup X in Cygwin? + +A: No, unfortunately I haven't got time to help with Cygwin related +user problems, please read Cygwin related web sites, newsgroups and +mailing lists. + +Q: Why is the instruction so long? Is it really that complicated? + +A: Partly it's long because I babble too much, partly because I've +described as much as I could about the installation of the needed +tools. Once the tools are installed, building is quite easy. I also +have tried to make this instruction understandable for people with +limited Unix experience. Cygwin is a whole new environment to some +Windows users, why careful explanation of environment variables etc +seemed to be in place. The short story, for the experienced and +impatient is: + +* Get and install complete Cygwin (latest) +* (Buy and) Install Microsoft Visual studio 2005 and SP1 (or higher) +* Get and install Sun's JDK 1.4.2 +* Get and install NSIS 2.01 or higher (up to 2.30 tried and working) +* Get and install OpenSSL 0.9.7c or higher +* Get and unpack wxWidgets-2.8.9 or higher to /opt/local/pgm inside cygwin + - open /cygwin/opt/local/pgm/wxWidgets-2.8.9/build/msw/wx.dsw + - enable wxUSE_GLCANVAS, wxUSE_POSTSCRIPT and wxUSE_GRAPHICS_CONTEXT + in include/wx/msw/setup.h + - build all unicode release (and unicode debug) packages + - open /cygwin/opt/local/pgm/wxWidgets-2.8.9/contrib/build/stc/stc.dsw + - build the unicode release (and unicode debug) packages +* Get and unpack the erlang source distribution with Cygwin's tar. +* set ERL_TOP to where you unpacked the source distribution +* $ cd $ERL_TOP +* Get (from http://www.erlang.org/download/tcltk85_win32_bin.tar.gz) +and unpack the prebuilt TCL/TK binaries for windows with cygwin tar, +standing in $ERL_TOP +* Modify PATH and other environment variables so that all these tools +are runnable from a bash shell. Still standing in $ERL_TOP, issue the following +commands: +$ eval `./otp_build env_win32` +$ ./otp_build autoconf +$ ./otp_build configure +$ ./otp_build boot -a +$ ./otp_build release -a +$ ./otp_build installer_win32 +$ release/win32/otp_win32_<OTP version> /S + +Voila! "Start->Programs->Erlang OTP <OTP version>->Erlang" starts the Erlang +Windows shell. + + +Tools you need and their environment +------------------------------------ + +You need some tools to be able to build Erlang/OTP on Windows. Most +notably you'll need Cygwin and Microsoft VC++, but you also might want +a Java compiler, the NSIS install system and OpenSSL. Only VC++ costs +money, but then again it costs a lot of money, I know... +Well' here's the list: + +* Cygwin, the very latest is usually best. Get all the development +tools and of course all the basic ditto. In fact getting the complete +package might be a good idea, as you'll start to love Cygwin after a +while if you're accustomed to Unix. Make sure to get jar and also make +sure *not* to install a Cygwin'ish Java... The Cygwin jar command is +used but Sun's Java compiler and virtual machine... + +URL: http://www.cygwin.com + +- get the installer from the web site and use that to install +Cygwin. Be sure to have fair privileges. If you're on a NT domain you +should consider running "mkpasswd -d" and "mkgroup -d" after the +installation to get the user databases correct. See their respective +manual pages. + +When you start you first bash shell, you will get an awful prompt. You +might also have a PATH environment variable that contains backslashes +and such. Edit $HOME/.profile and $HOME/.bashrc to set fair prompts +and set a correct PATH. Also do a "export SHELL" in .profile. For some +non-obvious reason the environment variable $SHELL is not exported in +bash. Also note that .profile is run at login time and .bashrc when +sub shells are created. You'll need to explicitly source .bashrc from +.profile if you want the commands there to be run at login time (like +setting up aliases, shell functions and the like). I personally +usually do like this at the end of .profile: +------------------ +ENV=$HOME/.bashrc +export ENV +. $ENV +---------------- + +You might also, if you're a hard core type of person at least, want to +setup X-windows (XFree86), that might be as easy as running startx +from the command prompt and it might be much harder. Use Google to +find help... + +If you don't use X-windows, you might want to setup the Windows +console window by selecting properties in the console system menu +(upper left corner of the window, the Cygwin icon in the title +bar). Especially setting a larger screen buffer size (lines) is useful +as it gets you a scrollbar so you can see whatever error messages +that might appear... + +If you want to use (t)csh instead of bash you're on your own, I +haven't tried and know of no one that has. I expect +that you use bash in all shell examples. + +* Microsoft Visual Studio 2005 SP1. Please don't skip the service +pack! The installer might update your environment so that you can run +the 'cl' command from the bash prompt, then again it might +not... There is always a BAT file in VC\Bin under the installation +directory (default C:\Program Files\Microsoft Visual Studio 8) called +VCVARS32.BAT. Either add the environment settings in that file to the +global environment settings in Windows or add the corresponding BASH +environment settings to your .profile/.bashrc. For example, in my case +I could add the following to .profile +------------------------------------------------------------ +#Visual C++ Root directory as Cygwin style pathname +VCROOT=/cygdrive/c/Program\ Files/Microsoft\ Visual\ Studio 8 + +# Visual C++ Root directory as Windows style pathname +WIN_VCROOT="C:\\Program Files\\Microsoft Visual Studio 8" + +# The PATH variable should be Cygwin'ish +PATH=$VCROOT/Common7/IDE:$VCROOT/VC/BIN:$VCROOT/Common7/Tools:\ +$VCROOT/Common7/Tools/bin:$VCROOT/VC/PlatformSDK/bin:$VCROOT/SDK/v2.0/bin:\ +$VCROOT/VC/VCPackages:$PATH + +# Lib and INCLUDE should be Windows'ish +# Note that semicolon (;) is used to separate Windows style paths but +# colon (:) to separate Cygwin ditto! + +LIBPATH=$WIN_VCROOT\\VC\\ATLMFC\\LIB + +LIB=$WIN_VCROOT\\VC\\ATLMFC\\LIB\;$WIN_VCROOT\\VC\\LIB\;\ +$WIN_VCROOT\\VC\\PlatformSDK\\lib\;$WIN_VCROOT\\SDK\\v2.0\\lib + +INCLUDE=$WIN_VCROOT\\VC\\ATLMFC\\INCLUDE\;$WIN_VCROOT\\VC\\INCLUDE\;\ +$WIN_VCROOT\\VC\\PlatformSDK\\include + +export PATH LIB INCLUDE +-------------------------------------------------------------- + +Make a simple hello world and try to compile it with the 'cl' command +from within bash. If that does not work, your environment needs +fixing. Also remember to fix up the PATH environment, especially old +Erlang installations might have inserted quoted paths that Cygwin does +not understand. Remove or correct such paths. There should be no +backslashes in your path environment variable in Cygwin bash, but LIB +and INCLUDE should contain Windows style paths with semicolon, +drive letters and backslashes. + +* Sun's Java JDK 1.5.0 or higher. Our Java code (jinterface, ic) is +written for JDK 1.5.0. Get it for Windows and install it, the JRE is +not enough. If you don't care about Java, you can skip this step, the +result will be that jinterface is not built. + +URL: http://java.sun.com + +Add javac *LAST* to your path environment in bash, in my case this means: +-------------------------------------------------------------- +PATH="$PATH:/cygdrive/c/Program Files/Java/jdk1.5.0_17/bin" +-------------------------------------------------------------- +No CLASSPATH or anything is needed. Type "javac" at the bash prompt +and you should get a list of available Java options. Make sure by +typing "which java" that you use the Java you installed. Note however that +Cygwin's jar.exe is used, that's why the JDK bin-directory should be +added last in the PATH. + +* Nullsoft NSIS installer system. You need this to build the self +installing package. It's a free open source installer that's much +nicer to use than the commercial Wise and Install shield +installers. This is the installer we use for commercial releases as +well from R9C an on. +URL: http://www.nullsoft.com/free/nsis +Install the lot, especially the modern user interface components, as +it's definitely needed. Put "makensis" in your path, in my case: +-------------------------------------------------------------- +PATH=/cygdrive/c/Program\ Files/NSIS:$PATH +-------------------------------------------------------------- +type makensis at the bash prompt and you should get a list of options +if everything is OK. + +* OpenSSL for Windows. This is if you want the SSL and crypto +applications to compile (and run). Go to http://www.openssl.org, click +on the "Related" link and then on the "Binaries" link (upper right +corner of the page last time I looked), you can then reach the +"Shining Lights Productions" Web site for Windows binaries +distributions. Get the latest or 0.9.7c if you get trouble with the +latest. It's a nifty installer. The rest should be handled by +configure, you needn't put anything in the path or anything. + +If you want to build openssl for windows yourself (which might be +possible, as you wouldn't be reading this if you weren't a +compile-it-yourself person), you either have to put the resulting +DLL's in your path or in the windows system directory and either +specify where you put the includes etc with the configure-parameter +--with-ssl=<cygwin path to the root> or put your installation directly +under c:\OpenSSL. The directory structure under the installation root +for OpenSSL is expected to be one with subdirectories named "include", +"bin" and "lib", possibly with a "VC" subdirectory of "lib" containing +the actual .lib files. Note that the cygwin distributed OpenSSL cannot be +used, it results in cygwin depending binaries and it has unix style +archives (.a, not .lib). + +* Building with wxWidgets. Download wxWidgets-2.8.9 or higher patch +release (2.9.* is a developer release which currently does not work +with wxErlang). +Install or unpack it to DRIVE:/PATH/cygwin/opt/local/pgm +Open from explorer (i.e. by double clicking the file) +C:\cygwin\opt\local\pgm\wxMSW-2.8.10\build\msw\wx.dsw +In Microsoft Visual Studio, click File/Open/File, locate and +open: C:\cygwin\opt\local\pgm\wxMSW-2.8.10\include\wx\msw\setup.h +enable wxUSE_GLCANVAS, wxUSE_POSTSCRIPT and wxUSE_GRAPHICS_CONTEXT +Build it by clicking Build/Batch Build and select all unicode release +(and unicode debug) packages. +Open C:\cygwin\opt\local\pgm\wxMSW-2.8.10\contrib/build/stc/stc.dsw +and batch build all unicode packages. + +* The Erlang source distribution. The same as for Unix +platforms. Preferably use tar from within Cygwin to unpack the source +tar.gz (tar zxf otp_src_R13B03.tar.gz). + +set the environment ERL_TOP to point to the root directory of the +source distribution. Let's say I stood in $HOME/src and unpacked +otp_src_R13B03.tar.gz, I then add the following to .profile: +-------------------------------------------------------- +ERL_TOP=$HOME/src/otp_src_R13B03 +export $ERL_TOP +-------------------------------------------------------- + +* The TCL/TK binaries. You could compile Tcl/Tk for windows yourself, +but you can get a stripped down version from our website which is +suitable to include in the final binary package. If you want to supply +tcl/tk yourself, read the instructions about how the tcl/tk tar file +used in the build is constructed under $ERL_TOP/lib/gs/tcl. The easy +way is to download +http://www.erlang.org/download/tcltk85_win32_bin.tar.gz and unpack it +standing in the $ERL_TOP directory. This will create the file +win32.tar.gz in $ERL_TOP/lib/gs/tcl/binaries. + +One last alternative is to create a file named 'SKIP' in the +$ERL_TOP/lib/gs/ after configure is run, but that will give you an +erlang system without gs (which might be okay as you probably will use +wx anyway). + +The shell environment +--------------------- + +So, if you have followed the instructions above, when you start a bash +shell, you should have an INCLUDE environment with a Windows style +path, a LIB environment variable also in Windows style, and finally a +PATH that let's you reach cl, makensis, javac etc from the +command prompt (use "which cl" etc to verify from bash). + +You should also have an ERL_TOP environment variable that is *Cygwin +style*, and points to a directory containing, among other files, the +script "otp_build". + +A final massage of the environment is needed, and that is done by +the script $ERL_TOP/otp_build. Start bash and do the following, note +the "back-ticks" (`), can be quite hard to get on some keyboards, but +pressing the back-tick key followed by the space bar might do it... + +------------------------ +$ cd $ERL_TOP +$ eval `./otp_build env_win32` +------------------------ +If you're unable to produce back-ticks on your keyboard, you can use +the ksh variant: +------------------------ +$ cd $ERL_TOP +$ eval $(./otp_build env_win32) +------------------------ + +This should do the final touch to the environment and building should +be easy after this. You could run "./otp_build env_win32" without +"eval" just to see what it does, and to see that the environment it +sets seems OK. The path is cleaned of spaces if possible (using DOS +style short names instead), the variables OVERRIDE_TARGET, CC, CXX, AR +and RANLIB are set to their respective wrappers and the directories +$ERL_TOP/erts/etc/win32/cygwin_tools/vc and +$ERL_TOP/erts/etc/win32/cygwin_tool are added first in the PATH. + +Try now a "which erlc". That should result in the erlc wrapper script +(which does not have the .sh extension, for reasons best kept +untold...). It should reside in $ERL_TOP/erts/etc/win32/cygwin_tools. +You could also try "which cc.sh", which "ar.sh" etc. + +Now you're ready to build... + + +Building and installing +----------------------- +Now it's assumed that you have executed "eval `./otp_build env_win32`" +for this particular shell... + +Building is easiest using the otp_build script. That script takes care +of running configure, bootstrapping etc on Windows in a simple +way. The otp_build script is the utility we use ourselves to build on +different platforms and it therefore contains code for all sorts of +platforms. The principle is, however, that for non-Unix platforms, one +uses "./otp_build env_<target>" to set up environment and then the +script knows how to build on the platform "by itself". You've already +run "./otp_build env_win32" in the step above, so now it's mostly like +we build on any platform. OK, here are then steps; Assuming you will +want to build a full installation executable with NSIS, you can omit +<installation directory> and the release will be copied to +$ERL_TOP/release/win32: and there is where the packed self installing +executable will reside too. + +$ ./otp_build autoconf # Ignore the warning blob about versions of autoconf +$ ./otp_build configure <optional configure options> +$ ./otp_build boot -a +$ ./otp_build release -a <installation directory> +$ ./otp_build installer_win32 <installation directory> # optional + +Now you will have a file called otp_win32_R12B.exe in the <installation +directory>, i.e. $ERL_TOP/release/win32. + +Lets get into more detail: + +$ ./otp_build autoconf - This step rebuilds the configure scripts to +work correctly in the cygwin environment. In an ideal world, this +would not be needed, but alas, we have encountered several +incompatibilities between our distributed configure scripts (generated +on a Linux platform) and the cygwin environment over the +years. Running autoconf on cygwin ensures that the configure scripts +are generated in a cygwin-compatible way and that they will work well +in the next step. + +$ ./otp_build configure - This runs the newly generated configure scripts +with options making configure behave nicely. The target machine type is +plainly "win32", so a lot of the configure-scripts recognize this +awkward target name and behave accordingly. The CC variable also makes +the compiler be cc.sh, which wraps MSVC++, so all configure tests +regarding the C compiler gets to run the right compiler. A lot of the +tests are not needed on Windows, but I thought it best to run the +whole configure anyway. The only configure option you might want to +supply is --with-ssl, which might be needed if you have built your own +openssl distribution. The Shining Lights distribution should be found +automatically by configure, if that fails, add a --with-ssl=<dir> that +specifies the root directory of your OpenSSL installation. + +$ ./otp_build boot -a - This uses the bootstrap directory (shipped +with the source, $ERL_TOP/bootstrap) to build a complete OTP +system. It first builds an emulator and sets up a minimal OTP system +under $ERL_TOP/bootstrap, then starts to compile the different OTP +compilers to make the $ERL_TOP/bootstrap system potent enough to be +able to compile all Erlang code in OTP. Then, all Erlang and C code +under $ERL_TOP/lib is built using the bootstrap system, giving a +complete OTP system (although not installed). When this is done, one +can run Erlang from within the source tree, just type $ERL_TOP/bin/erl +and you should have a prompt. If you omit the -a flag, you'll get a +smaller system, that might be useful during development. Now +exit from Erlang and start making a release of the thing: + +$ ./otp_build release -a - Builds a commercial release tree from the +source tree, default is to put it in $ERL_TOP/release/win32, you can +give any directory as parameter (Cygwin style), but it doesn't really matter +if you're going to build a self extracting installer too. You could of +course build release to the final directory and then run ./Install.exe +standing in the directory where the release was put, that will create +a fully functional OTP installation. But let's make the nifty +installer: + +$ ./otp_build installer_win32 - Create the self extracting installer +executable. The executable otp_win32_<OTP version>.exe will be placed +in the top directory of the release created in the previous step. If +no release directory is specified, the release is expected to have +been built to $ERL_TOP/release/win32, which also will be the place +where the installer executable will be placed. If you specified some +other directory for the release (i.e. +./otp_build release -a /tmp/erl_release), you're expected to give the +same parameter here, (i.e. ./otp_build installer_win32 /tmp/erl_release). +You need to have a full NSIS installation and makensis.exe in your +path for this to work of course. Once you have created the installer, +you can run it to install Erlang/OTP in the regular way, just run the +executable and follow the steps in the installation wizard. To get all +default settings in the installation without any questions asked, you +run the executable with the parameter "/S" (capital S). like in: +------------------------------------------------------ +$ cd $ERL_TOP +$ release/win32/otp_win32_R13B03 /S +..... +------------------------------------------------------ +- and after a while Erlang will have been installed in +C:\Program Files\erl5.7.4, with shortcuts in the menu etc. + +*NOTE* Beginning with R9C, the Windows installer does *not* add Erlang +to the system wide path. If one wants to have Erlang in the path, one +has to add it by hand. + +The necessary setup of an Erlang installation is actually done by the +program Install.exe, which resides in the release top. That program +creates ".ini-files" and copies the correct boot scripts. If one has +the correct directory tree (like after a ./otp_build release -a), only +the running of Install.exe is necessary to get a fully functional +OTP. What the self extracting installer adds is (of course) the +possibility to distribute the binary easily, together with adding +shortcuts to the Windows start menu. There is also some adding of +entries in the registry, to associate .erl and .beam files with Erlang +and get nifty icons, but that's not something you'll really need to +run Erlang. The registry is also used to store uninstall information, +but if one has not used the self extracting installer, one cannot +(need not) do any uninstall, one just scratches the release directory +and everything is gone. Erlang/OTP does not *need* to put anything +in the Windows registry at all, and does not if you don't use the self +extracting installer. In other words the installer is pure cosmetics. + + +Development +----------- + +Once the system is built, you might want to change it. Having a test +release in some nice directory might be useful, but you also can run +Erlang from within the source tree. The target 'local_setup', makes +the program $ERL_TOP/bin/erl.exe usable and it also uses all the OTP +libraries in the source tree. + +If you hack the emulator, you can then build the emulator executable +by standing in $ERL_TOP/erts/emulator and do a simple + +$ make opt + +Note that you need to have run (cd $ERL_TOP && eval `./otp_build env_win32`) +in the particular shell before building anything on Windows. After +doing a make opt you can test your result by running $ERL_TOP/bin/erl. +If you want to copy the result to a release directory (say +/tmp/erl_release), you do this (still in $ERL_TOP/erts/emulator) + +$ make TESTROOT=/tmp/erl_release release + +That will copy the emulator executables. + +To make a debug build of the emulator, you need to recompile both +beam.dll (the actual runtime system) and erlexec.dll. Do like this + +$ cd $ERL_TOP +$ rm bin/win32/erlexec.dll +$ cd erts/emulator +$ make debug +$ cd ../etc +$ make debug + +- and sometimes + +$ cd $ERL_TOP +$ make local_setup + +So now when you run $ERL_TOP/erl.exe, you should have a debug compiled +emulator, which you will see if you do a: + +1> erlang:system_info(system_version). + +- in the erlang shell. If the returned string contains "[debug]", you +got a debug compiled emulator. + +To hack the erlang libraries, you simply do a "make opt" in the +specific "applications" directory, like: + +$ cd $ERL_TOP/lib/stdlib +$ make opt + +- or even in the source directory... + +$ cd $ERL_TOP/lib/stdlib/src +$ make opt + +Note that you're expected o have a fresh Erlang in your path when +doing this, preferably the plain R13B03 you have built in the previous +steps. You could also add $ERL_TOP/bootstrap/bin to your PATH before +rebuilding specific libraries, that would give you a good enough +Erlang system to compile any OTP erlang code. Setting up the path +correctly is a little bit tricky, you still need to have +$ERL_TOP/erts/etc/win32/cygwin_tools/vc and +$ERL_TOP/erts/etc/win32/cygwin_tools *before* the actual emulator +in the path. A typical setting of the path for using the bootstrap +compiler would be: + +$ export PATH=$ERL_TOP/erts/etc/win32/cygwin_tools/vc:$ERL_TOP/erts/etc/win32/cygwin_tools:$ERL_TOP/bootstrap/bin:$PATH + +That should make it possible to rebuild any library without hassle... + +If you want to copy a library (an application) newly built, to a +release area, you do like with the emulator: + +$ cd $ERL_TOP/lib/stdlib +$ make TESTROOT=/tmp/erlang_release release + +Remember that: + +- Windows specific C-code goes in the +$ERL_TOP/erts/emulator/sys/win32, $ERL_TOP/erts/emulator/drivers/win32 +or $ERL_TOP/erts/etc/win32. + +- Windows specific erlang code should be used conditionally and the +host OS tested in *runtime*, the exactly same beam files should be +distributed for every platform! So write code like: + +case os:type() of + {win32,_} -> + do_windows_specific(); + Other -> + do_fallback_or_exit() +end, + +That's basically all you need to get going. + +Final words +----------- +My hope is that the possibility to build the whole system on Windows +will open up for free development on this platform too. There are many +things one might want to do better in the Windows version, like the +window-style command prompt as well as pure Cygwin porting. Although i +realize it's a much larger step to start building on Windows (with all +the software you need) than for instance on Linux, I sincerely hope +that some of you will make the effort and start submitting Windows +friendly patches. + +The first build system for Erlang using Cygwin on Windows was created +by Per Bergkvist. I haven't used his build system, but it's rumored to +be good. The idea to do this came from his work, so credit is well +deserved. + +Of course this would have been completely impossible without the +excellent Cygwin package. The guys at Cygnus solutions and Redhat +deserves a huge THANKS! as well as all the other people in the free +software community who have helped in creating the magnificent +software that constitutes Cygwin. + +Good luck and Happy Hacking, +Patrik, OTP |