============================================================================ == BUILDING COIN ON WINDOWS == ============================================================================ Microsoft Visual Studio ======================= The source code archive for Coin comes with Microsoft Visual Studio files for building and installing the Coin library. Visual Studio 6, Visual Studio 7/7.1, and Visual Studio 8 are supported. At the last stage of the build, the Coin development kit is automatically installed into the directory the COINDIR environment variable points to. Set it to "C:\Coin3D" or wherever you want the Coin SDK to reside by using Control Panel => System => Advanced => Environment Variables and make sure you create that directory before starting the build - if the variable isn't set or the directory doesn't exist, the installation will break and you won't get a functional SDK. Using the source hierarchy as the SDK is not recommended - let Coin be installed, and use COINDIR from your other projects that use Coin. For Microsoft Visual Studio 6, you will find the complete build file setup in the directory "build/msvc6/". Select the dsw file. For Microsoft Visual Studio 7, you will find the complete build file setup in the directory build/msvc7/. Select the sln file. For Microsoft Visual Studio 8, you will find the complete build file setup in the directory build/msvc8/. Select the sln file. Other IDEs ========== We unfortunately don't provide project files for anything other than Visual Studio at this point. ============================================================================ == OLD OBSOLETED INFORMATION BELOW == ============================================================================ This below text is information about building Coin on MS Windows platforms with the Cygwin environment. Compilers ========= In-house we mostly use the Visual Studio 8 and Visual C++ 6 compilers when building on Windows. We have also had success reports from users about building Coin with the Intel compiler through using the Visual Studio project file setup for that. Building with GCC (primarily the mingw fork) on Windows is possible, but this setup is not something we maintain so it might not work out of the box at times. Environments ============ Microsoft Developer Studio -------------------------- With the release of Coin 2.0.0, we started shipping Microsoft Developer Studio files with the binary Coin installer. The binary installer can be found at http://www.coin3d.org/windows. These files are automatically generated on our side in the Cygwin environment. We are open for suggestions on how they ought to be changed, but since we don't create them manually we can only apply changes to the Developer Studio files that can go into the auto- generation process. Cygwin ------ Cygwin is a UNIX/POSIX-like environment from Cygnus. See www.cygwin.com. We often use this environment for building Coin, so it is usually up to date. Building Coin under MS Windows ============================== There are now two ways to build the Coin library with Microsoft Visual C++ on MS Windows. You can use Cygwin and compile Coin with regular GNU makefiles, or you can use a Microsoft Visual Studio Project and Workspace file for building Coin from the IDE. Section 01 -- Basic build instructions. ======================================= We've worked hard to get the configure and build process to be as straight forward and failsafe on as many platforms as possible, but since it uses some typical UNIX tools unfamiliar to most MSWindows developers our policy on the MSWindows platform is to provide pre-built binary SDKs -- and officially state that building on the Windows platform is not completely trivial. Anyway, you should be able to build the library if you have these components installed on your system: * Cygwin[1], latest release, with the packages needed to run a configure script[2] * Microsoft Visual C++ v6 or v7 [3] First, make sure Microsoft Visual C++ is accessible from the Cygwin shell. If you can run ``cl.exe'' from the bash command line on the following minimal, stand-alone sourcecode snippet: ---8<-- [snip] --------8<-- [snip] --------8<-- [snip] ----- #include int main(void) { (void)printf("hello world\n"); return 0; } ---8<-- [snip] --------8<-- [snip] --------8<-- [snip] ----- ...everything is probably set up for you already. If not, you need to add something like this to .bashrc and .bash_profile: NB: This setup is for MSVC++ 6.0. # the Cygwin path to the Microsoft Visual Studio directory... MSVS_HOME="/cygdrive/c/Program Files/Microsoft Visual Studio" win_MSVS_HOME=`cygpath -w "$MSVS_HOME"` PATH="$PATH:$MSVS_HOME/VC98/Bin:$MSVS_HOME/VC98/Lib" PATH="$PATH:$MSVS_HOME/Common/MSDev98/Bin" LIB="$win_MSVS_HOME\\VC98\\Lib" INCLUDE="$win_MSVS_HOME\\VC98\\Include" export PATH LIB INCLUDE For MSVC++ 7, the locations have changed. Try _something like_ the below instead of the corresponding four lines above. The lines are loosely based on a problem report, and not been verified by us yet though - please tell us if they need some tweaks, or work right out of the box so we might update this information. PATH="$PATH:$MSVS_HOME/VC7/Bin:$MSVS_HOME/VC7/Lib:$MSVS_HOME/VC7/PlatformSDK/Lib" PATH="$PATH:$MSVS_HOME/Common/MSDev7/Bin" LIB="$win_MSVS_HOME\\VC7\\Lib;$win_MSVS_HOME\\VC7\\platformSDK\\Lib" INCLUDE="$win_MSVS_HOME\\VC7\\Include;$win_MSVS_HOME\\VC7\\PlatformSDK\\Include" (Then try again to see that the MSVC environment is working. If not, you need to debug this on your end before proceeding.) Then, make sure you have not set the variables CC and CXX before running configure. You unset them with these commands: $ unset CC $ unset CXX Configure and build the same way as you would on UNIX-based systems, i.e. $ [srcdir]/configure $ make install To specify which C library Coin should be linked against, you should use the --with-msvcrt= option. You have the following choices (short aliases on the right): singlethread-static [ /ml | ml | libc ] (default) singlethread-static-debug [ /mld | mld | libcd ] multithread-static [ /mt | mt | libcmt ] multithread-static-debug [ /mtd | mtd | libcmtd ] multithread-dynamic [ /md | md | msvcrt ] multithread-dynamic-debug [ /mdd | mdd | msvcrtd ] Note that if you encounter any problems when trying to build on MSWindows, it is expected that you are able to do a minimum of troubleshooting yourself before contacting us. (If this is not an option, please consider using the pre-built binary installation packages we provide. Follow the download link from .) If you are confident that configure and/or build fails due to a mistake on our part, or you otherwise feel completely stuck, we will be happy to assist. A few notes about what seems to be the most common problems: a) configure reporting ``configure: error: no acceptable ld found in $PATH''. This is because you have not installed Cygwin's ``binutils'' package on your system. So install ``binutils'' and try again. (GNU GCC's ``ld'' isn't really needed for the build, since we use 100% native Microsoft Visual C++ tools, but there is a dependency on it in the configure script. This is out of our control for now, but we will likely investigate to see if we can get rid of it.) b) Problems related to spaces in paths for any of the components involved, for instance the path to the source code directory, or the build directory, or the installation directory, or to libraries we depend on. c) When trying to run the configure script, you get the following error message: configure is not recognized as an internal or external command operable program or batch file This is probably because you tried to run the configure script from a DOS shell window. You need to use a Cygwin bash shell. d) During ``make install'', you get the following error: make[2]: Entering directory `/coin-builddir/debug' /bin/bash ../cfg/mkinstalldirs /coin-installdir/bin /usr/bin/install -c ../cfg/wrapmsvc.exe /coin-installdir/bin/wrapmsvc.exe /usr/bin/install: cannot change ownership of `/coin-installdir/bin/wrapmsvc.exe': Invalid argument This is a Cygwin installation problem on your local system, which causes ``chmod'' to not work as expected due to erroneous configuration of users and / or permissions. You will have to figure out how to solve this one by yourself, as we haven't been able to reproduce it. We'll include more information here if we get further feedback from users with this problem. e) We have various reports of problems related to network NTFS file systems mounted under Cygwin. The problems seems to stem from the fact that "test -x" on what should be an executable does not recognize it as such. One possible work-around is to mount the disk with "mount -x" from Cygwin, which makes *all* files executable. Another, perhaps preferable, fix is to just not use a network share for storing the source code directory, or for setting up the build and install directories. f) We have one report on lib.exe failing silently when building simage, libCoin and SoWin with VS.NET with options "--disable-shared" and "--enable-static" to configure. A workaround is to do manual creation of the lib-file, after which ``make install'' will execute ok. g) The Qt library for MSWindows has a file ''install.exe'' in it's installation package. If the $QTDIR/bin/ path comes before the path to the Cygwin /usr/bin/install.exe tool, the Qt install.exe will be invoked upon ''make install''. To get around this, set up your $PATH to have Cygwin's /usr/bin/ listed before $QTDIR/bin/. --- [1] [2] 'bash', 'binutils', and 'make' may not be part of the standard package set, but need to be present. Include 'cvs' if you want to stay in sync with the development source code of Coin, plus 'perl' and 'doxygen' if you want to build a local copy of the API documentation. [3] The Microsoft Visual C++ build tools are now available for free: http://msdn.microsoft.com/visualc/vctoolkit2003/ Note that this only includes the command-line tools. The MS Visual Studio IDE tools are not available, it seems. Section 02 -- Known run-time problems ===================================== This section lists all our known run-time problems seen with the Coin library on the Microsoft Windows platform -- excluding what we know to be specific bugs in our code: * We've had one report about the Radeon OpenGL driver crashing when using 3D textures. The problem was reproducible with the SoGuiExamples/nodes/texture3 example. The Coin-user reporting the problem could not assist us with tracing into the problem, so we would like to get in touch with someone with a Radeon card under MS Windows who could help us find the source of the problem. The OpenGL driver in question identifies as: GL_VERSION == '1.3.3302 Win2000 Release' GL_VENDOR == 'ATI Technologies Inc.' GL_RENDERER == 'Radeon 7500 DDR x86/SSE2' Section 03 -- Tracing into Coin from the MSVC++ IDE. ==================================================== We've had reports about problems getting symbol and source code information when debugging into Coin and / or SoQt or SoWin from the Microsoft Visual C++ IDE. This quick description should hopefully get you on your way if you experience the same kind of problem: o You need to specify the path to the source code of the library. This is a setting of Microsoft Visual C++ and is therefore valid for any project you work on: Tools -> Options -> Directories: From the pop up menu "show directories for", choose "source files". Add the path(s) to where the source code of the libraries can be found. o However, it may still happen that Visual C++ complains about not finding some files and will give you the possibility to specify the location of the specific files. This is common with the SoQt & SoWin libraries. The reason for this is that a lot of the source code files for those libraries are generated from *templates* on-the-fly while building, and the "real" sources will then reside in the build-directory. So if MSVC++ wants to know where source code files for SoQt/SoWin classes are, point it at your build directory. o We have not found out how to specify the path(s) to the source code using environment variables (as you can do for specifying the location of the *.dll files). Therefore you have to set the absolute path in the settings as described above. In case you know how to do this, please contact us and we'll add it to this description. Section 04 -- Building non-default configurations. ================================================== For builds with Microsoft Visual C++, any additional options to the cl.exe and link.exe tools can be given by setting the environment variables CL and LINK, respectively. These matches what you can do with CPPFLAGS / CFLAGS / CXXFLAGS and LDFLAGS on typical UNIX compiler systems. For additional information, see the following article in Microsoft's Developer Knowledge Base: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vccore/html/_core_cl_environment_variable.asp * FIXME: explain how to build release versions of the libraries. 20011019 mortene. (One snippet of information wrt release builds: "-O2" (or whatever optimization level is wanted) should be manually added by the user to CFLAGS/CXXFLAGS.) * FIXME: explain how to build static versions of the libraries. 20011019 mortene. * FIXME: explain how to build the full library-chain on top of other versions of the Microsoft C libraries than the default one. 20011019 mortene. Section 05 -- Static versus dynamic libraries ============================================= Note that MS Visual C++ and other MSWin compilers / linkers are a bit peculiar in that building a library as a DLL leaves you with both a .dll-file and a .lib-file. When you link against the library, you do it against the .lib-file, but when the system loads the executable it will of course link against the .dll. Using a library in a solely "static" fashion leaves you with just a .lib-file. To build SoWin for use as a static library, you need to add the options "--enable-static" and "--disable-shared" when invoking the configure script. Section 06 -- What is this ``configure'' thing? =============================================== The configure script is a script that first determines what kind of system it's being run on, then tries to locate a compiler, and then uses the compiler to probe the system for its capabilities. For instance, which optional utility libraries are available? The configure script tries to link with all the potential libraries that we might want to use. If the linking works, the library is there. If the link-test fails, then it's not. Another thing that is often probed is whether a library is new enough so that it contains some function foo()? Depending on these tests, the configure script sets up a header-file called "config.h" that contains #define settings for what the configure script managed to find. This header is included from all the sources that needs system-dependent code blocks. In this way you tune the library on individual features instead of basing the compilation on which platform it is that is being used. The configure script also has the purpose of figuring out how the compiler should be used when you build the library. The result of these tests are put into all the Makefile files that are generated at the end of the configure run. The Makefile files are created through keyword substitution in the Makefile.in templates you will see in the source hierarchy. After having run configure, all system characteristics should be figured out and the Makefiles should be set up so you only need to type "make" to get everything built. Another feature of this setup is to run the configure script from an empty directory. This will create an an empty directory structure with makefiles that will compile the sources out of the source directory while putting the object files in the newly created directory structure. This means you can keep your sources in one place (even on a read-only medium like a CDROM), and build the library in some temporary location that can be scrapped after you have built and installed the library. Section 07 -- Library Dependencies ==================================== To find out which dynamically loadable libraries an application loads (depends on), the following commands might be of help: MSVC 6: depends MSVC 7: dumpbin /dependents INCOMING [Sven-Kåre Evenseth] I ran into some problems building Coin 2.1.1 on windows today. We use cygwin, and // to prefix drives. It seems that use of // isn't very popular anymore... When running make install, it tries to do a mkdir -p -- //driveletter/some/long/path/being/created and fails, complaining about //driveletter: no such file or directory The problem is solved when changing how drives are prefixed in the registry key: HKEY_LOCAL_MACHINE\SOFTWARE\Cygnus Solutions\Cygwin\mounts v2 It looks like anything goes, as long as there is something inbetween two slashes (/cygdrive/, /c/, /sunday_bloody_sunday/ etc). See also: http://cygwin.com/faq/faq_4.html#SEC34 http://sources.redhat.com/ml/cygwin/2001-09/msg00014.html