README

   1 Welcome to the fun world of open-source.
   2
   3 This file is to help you get started using the source and will hopefully
   4 answer most questions.
   5
   6 Here are some links to external packages you may or maynot need:
   7
   8 openssl:  http://www.openssl.org
   9 python:  http://www.python.org
  10 mxtexttools:http://www.egenix.com/files/python/mxTextTools.html (python lib)
  11 libjpeg:  http://www.ijg.org/
  12 libpng:  http://www.libpng.org/pub/png/
  13 zlib:   http://www.gzip.org/zlib/
  14 ode:    http://q12.org/ode/ode.html
  15 openal:  http://www.openal.org/home/            (for linux/windows)
  16         sdl: http://www.libsdl.org/index.php (for openal)
  17         smpeg: http://www.lokigames.com/development/smpeg.php3 (for openal)
  18 fmod: http://www.fmod.org/
  19
  20 mozilla: http://www.mozilla.org/
  21 nspr:  ftp://ftp.mozilla.org/pub/nspr/releases
  22         (side note: on debian linux you will need mozilla-dev and libnspr-dev)
  23
  24 glut:   http://www.opengl.org/developers/documentation/glut.html
  25
  26 If you do not have GL you will also need mesa:
  27 mesa:   http://www.mesa3d.org
  28
  29 *********************************************************************
  30 *********************************************************************
  31 We are in the process of moving things over to automake/autoconf
  32 The old makefiles are still in place and will work.
  33 If you want to get a working blender skip down to the next section
  34 and use this readme as a guide.
  35
  36 If you want to play with the new autoconf environment take a look at
  37 doc/autoconfig.txt
  38
  39 *********************************************************************
  40 *********************************************************************
  41
  42 --Notes on compiling mxTextTools----------------------------------------------
  43 To get the latest version to compile on my machine I had to
  44 edit mxSetup.py and remove /usr/include from INCLPATH for it to build
  45 properly.
  46 (after doing this you need to edit blender/source/Makefile and
  47 fix the pointer to it I'm still working on automating this)
  48
  49 --------------Basic Makefile TIPS---------------------------------------
  50 Assuming you are using tcsh/csh do the following before compiling.
  51 #Set this to wherever you have extracted the source.
  52 setenv NANBLENDERHOME `pwd`
  53 setenv MAKEFLAGS "-w -I$NANBLENDERHOME/source"
  54
  55 Or for bash/sh do this:
  56 NANBLENDERHOME=`pwd`
  57 export NANBLENDERHOME
  58 MAKEFLAGS="-w -I$NANBLENDERHOME/source"
  59 export MAKEFLAGS
  60
  61 Then edit source/nan_definitions.mk to fit you're environment.
  62 (You'll want to change things like NAN_OPENSSL,NAN_JPEG, NAN_PNG etc..
  63 to point to where you have it installed)
  64
  65 If you want to integrate the game-engine in Blender, you might want
  66 to uncomment the following line in nan_compile.mk:
  67 #CFLAGS += -DGAMEBLENDER=1
  68 The define is disabled by default because there still are still some
  69 problems with this at the moment.
  70
  71 If you tried to just have a go at making stuff you might wind up with
  72 an empty file /tmp/.nanguess
  73 You need to remove the empty file and it will get created automatically
  74 by $NANBLENDERHOME/source/tools/guess/guessconfig after you have
  75 setup the NANBLENDERHOME variable.
  76
  77 After that cd $NANBLENDERHOME/intern
  78 make
  79 make install
  80
  81 cd $NANBLENDERHOME/source/ode
  82 Look at the README_BLENDER and follow instructions
  83
  84 Then cd $NANBLENDERHOME/source
  85 make
  86
  87 If you have any problems with the above post a message to the Forums on
  88 www.blender.org
  89
  90 ----------------------WINDOWS TIPS--------------------------------------
  91
  92 When building Blender on Windows you have three choices:
  93 METHOD 1. Build using the old NaN Makefiles.
  94 METHOD 2. Build using the new automake/autoconf files
  95 METHOD 3. Use Microsoft Visual Studio project files
  96
  97 These directions are for method 3. Method 1 was used in Nan in combination
  98 with Cygwin. I don't know if somebody ever tried method 2.
  99
 100 EXTERNAL LIBARIES
 101 All external libraries that Blender depends on are found in CVS in
 102 precompiled form. If you did not already do so, check out
 103 blender/lib/windows from CVS. If you prefer to build or download those
 104 libraries yourself, there are some directions below.
 105
 106 INTERN LIBRARIES:
 107 The first thing you need to do is to build the Blender "intern" libraries.
 108 You need to have Python installed on your machine.
 109
 110 Open the workspace in the $NANBLENDERHOME/intern/make/msvc_6_0 directory.
 111 Build the "build_install_all" project. This will build all the intern libraries
 112 and installs them in the $NANBLENDERHOME/lib/windows directory.
 113
 114 If the post build step (copying the libraries to their destinations) fails,
 115 this is probably due to the fact that MSVC can't find the XCOPY command as
 116 happened to me on an XP system. MSVC has it's own PATH that you can set through
 117 the options. Open options from the menu: Tools->Options. Go to the directories
 118 tab and select "Executable files" from the drop down menu. Now add you SYSTEM32
 119 directory.
 120
 121 The last project build is the python_freeze project that will freeze python code
 122 for compilation and linking with Blender's C code. At the moment, this should be
 123 automatic except that batch file probably does not find Python. If this is the
 124 case, follow the same procedure as was mentioned above for the XCOPY command
 125 to add Python to your path.
 126
 127 BUILDING BLENDER
 128
 129 Open the workspace $NANBLENDERHOME/projectfiles/creator/blendercreator.dsw.
 130 This contains the following four main projects:
 131 blendercreator    Builds the creator
 132 blenderpublisher  Builds the publisher
 133 GP_ghost          Builds the stand-alone game player
 134 GP_axctl          Builds the ActiveX control
 135
 136 Choose the project you want to build and hit F7. If all is well it should build
 137 with a lot of warnings but no errors.
 138
 139 BUILDING/DOWNLOADING EXTERNAL LIBRARIES
 140 If you don't want to use the precompiled libraries you can download and/or
 141 build them yourself. Here are some directions.
 142
 143 JPEG:
 144 BINARY LIBRARY:
 145 Go to sourceforge.net, navigate to the GnuWin32 project and download
 146 libjpeg-6b-lib.zip. Rename the unzipped directory "jpeg" and copy it to the
 147 $NANBLENDERHOME/lib/windows directory.
 148 FROM SOURCES:
 149 Download the jpeg sources from http://www.ijg.org/. Go into the source
 150 directory and copy the file jconfig.vc to jconfig.h. Now start a command box
 151 and run nmake /f makefile.vc (assuming nmake is in your path, if not run the
 152 vcvars32.bat batch file located in the VC98/Bin directory of the MSVC
 153 installation directory first).
 154 Copy these include files: jconfig.h, jerror.h, jmorecfg.h, jpeglib.h
 155 from the build directory to the lib tree in this directory:
 156 $NANBLENDERHOME/lib/windows/jpeg/include
 157 The file libjpeg.lib should be copied to:
 158 $NANBLENDERHOME/lib/windows/jpeg/lib
 159
 160 PNG:
 161 Go to sourceforge.net, navigate to the GnuWin32 project and download
 162 libpng-1.2.4-1-lib.zip. Rename the unzipped directory "png" and copy it to the
 163 $NANBLENDERHOME/lib/windows directory.
 164
 165 ZLIB:
 166 Go to sourceforge.net, navigate to the GnuWin32 project and download
 167 zlib-1.1.4-lib.zip. Rename the unzipped directory "zlib" and copy it to the
 168 $NANBLENDERHOME/lib/windows directory.
 169
 170
 171 If you have any problems with the above post a message to the Forums on
 172 www.blender.org
 173
 174 ----------------------Mac OSX TIPS--------------------------------------
 175 When building Blender on OSX you have three choices:
 176 METHOD 1. Build using the old NaN Makefiles.
 177 METHOD 2. Build using the new automake/autoconf files
 178 METHOD 3. Use the Project Builder project
 179
 180 METHOD 1 and 3
 181 The first 4 steps are th same for methods 1 and 3. Only the actual Blender
 182 build step number 5 is different.
 183
 184 Step1:
 185 If you want to follow method 1 and 3, follow the instructions above to set the
 186 environment variables. You don't need to edit the Makefiles. They should work
 187 out of the box in combinations with some external libraries that should be on
 188 your system in a fixed location.
 189
 190 Step 2:
 191 You can use the package installer fink (http://fink.sourceforge.net/) for some
 192 of the external libraries:
 193 1. openssl (fink install openssl)
 194 2. jpeg    (fink install libjpeg)
 195 3. png     (fink install libpng)
 196
 197 Step 3:
 198 The rest of the external libraries are present in CVS in binary format so you
 199 don't have to download them. Precompiled libraries are found in CVS in
 200 directory:
 201 $NANBLENDERHOME/lib/darwin-6.1-powerpc
 202 If you are not running on a darwing kernel 6.1 (which is likely if you auto-
 203 update your system, you might want to add a symbolic link in the
 204 $NANBLENDERHOME/lib/ directory. For example, if you work on a 6.2 kernel:
 205 ln -s darwin-6.1-powerpc darwin-6.2-powerpc
 206
 207 Step 4:
 208 Start the build process by building Blender's "intern" libraries. Navigate to
 209 $NANBLENDERHOME/intern and type make. This will build the intern libaries which
 210 will be installed into the $NANBLENDERHOME/lib/darwin-6.1-powerpc (thanks to
 211 the symbolic link).
 212 Now you can choose how to build Blender itself; using the Makefiles or the
 213 Project Builder project.
 214
 215 Step 5 METHOD 1:
 216 Navigate to $NANBLENDERHOME/source and type make.
 217
 218 Step 5 METHOD 3:
 219 The project Builder project can be found in the directory:
 220 $NANBLENDERHOME/projectfiles/pb_2_0_1
 221 Start Project Builder open the blender.pbproj project, choose a target (blender
 222 or player) and build.
 223
 224 Step 6:
 225 Although the Makefiles in the intern directory run ranlib on the libraries
 226 built, the gcc linker complains about ranlib not being run. Until there is a
 227 solution, you will need to run ranlib by hand once in a while when the make
 228 breaks. Luckily, the error message lists the full path of the file to run
 229 ranlib on... Anybody out there with a real solution? I guess the problem arises
 230 from copying the files from one location to the other...
 231
 232
 233 BUILDING EXTERNAL LIBRARIES
 234 If you don't want to use the precompiled libraries you can download and/or
 235 build them yourself. Here are some directions.
 236
 237 PYHON:
 238 Mac OSX 10.2 (Jaguar) now comes with Python (2.2.1) pre-installed. This is fine
 239 for producing the "frozen" Python code found in the intern directory. However,
 240 the installation does not contain the python library to link against (at least
 241 I could not find it). You could use fink to install Python but that Python
 242 installation depends on X being installed and that is a large installation.
 243
 244 If you prefer the easy way: download Python 2.2.2 from http://www.python.org.
 245 Follow the instructions to in the documentation to install it on your box. If
 246 you run OSX 10.2 it should install just fine. Basically a configure and a
 247 "make" will do the job. The result is a Python library that should be copied to
 248 the library tree together with the associated header files.
 249
 250 Create the following  directories:
 251 $NANBLENDERHOME/lib/darwin-6.1-powerpc/python/include/python2.2
 252 $NANBLENDERHOME/lib/darwin-6.1-powerpc/python/lib/python2.2/config
 253 Now copy the include files and the libpython2.2.a library to those locations.
 254
 255 FMOD:
 256 Download FMOD from http://www.fmod.org/ and unpack with StuffIt Expander. The
 257 archive contains header files and a library. Copy those to these directories
 258 (that you need to create first):
 259 $NANBLENDERHOME/lib/darwin-6.1-powerpc/fmod/include
 260 $NANBLENDERHOME/lib/darwin-6.1-powerpc/fmod/lib
 261
 262 ODE:
 263 Ode is currently included in the source tree of Blender. This might change in
 264 the close future. But for now you don't need to download Ode.
 265 If you want to build ODE yourself, you'll have to edit a config file of ODE first.
 266 go to $NANBLENDERHOME/source/ode/config and edit the file "user-settings" so
 267 that platform is equal to osx (PLATFORM=osx).
 268
 269 If you have any problems with the above post a message to the Forums on
 270 www.blender.org