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