This is a fun one ;)
[blender.git] / 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 python:      http://www.python.org
11 mxtexttools: http://www.egenix.com/files/python/mxTextTools.html (python lib)
12 libjpeg:     http://www.ijg.org/
13 libpng:      http://www.libpng.org/pub/png/
14 zlib:        http://www.gzip.org/zlib/
15 ode:         http://opende.sourceforge.net/
16 openal:      http://www.openal.org/home/                (for linux/windows)
17     sdl:     http://www.libsdl.org/index.php (for openal)
18     smpeg:   http://www.lokigames.com/development/smpeg.php3 (for openal)
19 fmod: http://www.fmod.org/
20
21 mozilla: http://www.mozilla.org/
22 nspr:  ftp://ftp.mozilla.org/pub/nspr/releases
23         (side note: on debian linux you will need mozilla-dev and libnspr-dev)
24
25 glut:    http://www.opengl.org/developers/documentation/glut.html
26
27 If you do not have GL you will also need mesa:
28 mesa:    http://www.mesa3d.org
29
30 For the translations to other languages than English you will need gettext,
31 freetype2 and FTGL. Note that these translations are not complete yet, some
32 time after the release of 2.27 they will be made available for download also.
33 We welcome feedback about the translated user interface, and even contributions
34 to the translation effort :)
35
36 gettext:     http://www.gnu.org/software/gettext/
37 freetype2:   http://www.freetype.org/
38 FTGL:        http://homepages.paradise.net.nz/henryj/code/#FTGL
39
40 FTGL needs a small patch to get glyphs with the right colour in the cache
41 --- FTGL/src/FTPixmapGlyph.cpp.orig     2003-05-10 16:07:45.000000000 +0200
42 +++ FTGL/src/FTPixmapGlyph.cpp  2003-05-10 16:09:19.000000000 +0200
43 @@ -33,3 +33,3 @@
44          // Get the current glColor.
45          float ftglColour[4];
46 -        glGetFloatv( GL_CURRENT_COLOR, ftglColour);
47 +        ftglColour[0] = ftglColour[1] = ftglColour[2] = ftglColour[3] = 1.0;
48
49
50 You may also need to modify the typedef for GLUTesselatorFunction in 
51 src/FTVectoriser.cpp if your on an undefined system.  To do that
52 check the following link to find out various platform identifiers.
53 http://www.blender.org/modules/documentation/intranet/conventions/codingstyleguide.html#3_2
54
55 *********************************************************************
56 *********************************************************************
57 We are in the process of moving things over to automake/autoconf
58 The old makefiles are still in place and will work.  
59 If you want to get a working blender skip down to the next section 
60 and use this readme as a guide.
61
62 If you want to play with the new autoconf environment take a look at 
63 doc/autoconfig.txt
64
65 *********************************************************************
66 *********************************************************************
67
68 --Notes on compiling mxTextTools----------------------------------------------
69 To get the latest version to compile on my machine I had to
70 edit mxSetup.py and remove /usr/include from INCLPATH for it to build
71 properly.
72 (after doing this you need to edit blender/source/Makefile and
73 fix the pointer to it I'm still working on automating this)
74
75 --------------Basic Makefile TIPS---------------------------------------
76 Edit source/nan_definitions.mk to fit your environment, be sure to edit the
77 block matching your OS. You will want to change variables like 
78 NAN_JPEG, NAN_PNG etc. to point to where you have those installed.
79
80 If you want to integrate the game-engine in Blender, you might want
81 to uncomment the following line in nan_compile.mk:
82 #CFLAGS += -DGAMEBLENDER=1
83 The define is disabled by default because there are still some
84 problems with this at the moment.
85
86 After adjusting things for your environment run 'make' (or use the nice hmake
87 script at blender/source/tools/hmake/hmake)
88
89 ----------------------WINDOWS TIPS--------------------------------------
90
91 When building Blender on Windows you have three choices:
92 METHOD 1. Build using the old NaN Makefiles.
93 METHOD 2. Build using the new automake/autoconf files
94 METHOD 3. Use Microsoft Visual Studio project files
95
96 These directions are for method 3. Method 1 was used in Nan in combination 
97 with Cygwin. I don't know if somebody ever tried method 2.
98
99 EXTERNAL LIBARIES
100 All external libraries that Blender depends on are found in CVS in 
101 precompiled form. If you did not already do so, check out 
102 blender/lib/windows from CVS. If you prefer to build or download those 
103 libraries yourself, there are some directions below.
104
105 INTERN LIBRARIES:
106 The first thing you need to do is to build the Blender "intern" libraries.
107 You need to have Python installed on your machine.
108
109 Open the workspace in the $NANBLENDERHOME/intern/make/msvc_6_0 directory.
110 Build the "build_install_all" project. This will build all the intern libraries
111 and installs them in the $NANBLENDERHOME/lib/windows directory.
112
113 If the post build step (copying the libraries to their destinations) fails,
114 this is probably due to the fact that MSVC can't find the XCOPY command as 
115 happened to me on an XP system. MSVC has it's own PATH that you can set through
116 the options. Open options from the menu: Tools->Options. Go to the directories
117 tab and select "Executable files" from the drop down menu. Now add you SYSTEM32
118 directory.
119
120 The last project build is the python_freeze project that will freeze python code
121 for compilation and linking with Blender's C code. At the moment, this should be
122 automatic except that batch file probably does not find Python. If this is the
123 case, follow the same procedure as was mentioned above for the XCOPY command
124 to add Python to your path.
125
126 BUILDING BLENDER
127
128 Open the workspace $NANBLENDERHOME/projectfiles/blender/blender.dsw
129
130 This contains the following three main projects:
131 blender           Builds the main executable
132 GP_ghost          Builds the stand-alone game player
133 GP_axctl          Builds the ActiveX control
134
135 Choose the project you want to build and hit F7. If all is well it should build
136 with a lot of warnings but no errors.
137
138 BUILDING/DOWNLOADING EXTERNAL LIBRARIES
139 If you don't want to use the precompiled libraries you can download and/or
140 build them yourself. Here are some directions.
141
142 JPEG:
143 BINARY LIBRARY:
144 Go to sourceforge.net, navigate to the GnuWin32 project and download 
145 libjpeg-6b-lib.zip. Rename the unzipped directory "jpeg" and copy it to the 
146 $NANBLENDERHOME/lib/windows directory.
147 FROM SOURCES:
148 Download the jpeg sources from http://www.ijg.org/. Go into the source 
149 directory and copy the file jconfig.vc to jconfig.h. Now start a command box
150 and run nmake /f makefile.vc (assuming nmake is in your path, if not run the
151 vcvars32.bat batch file located in the VC98/Bin directory of the MSVC 
152 installation directory first).
153 Copy these include files: jconfig.h, jerror.h, jmorecfg.h, jpeglib.h
154 from the build directory to the lib tree in this directory:
155 $NANBLENDERHOME/lib/windows/jpeg/include
156 The file libjpeg.lib should be copied to:
157 $NANBLENDERHOME/lib/windows/jpeg/lib
158
159 PNG:
160 Go to sourceforge.net, navigate to the GnuWin32 project and download 
161 libpng-1.2.4-1-lib.zip. Rename the unzipped directory "png" and copy it to the 
162 $NANBLENDERHOME/lib/windows directory.
163
164 ZLIB:
165 Go to sourceforge.net, navigate to the GnuWin32 project and download 
166 zlib-1.1.4-lib.zip. Rename the unzipped directory "zlib" and copy it to the 
167 $NANBLENDERHOME/lib/windows directory.
168
169
170 ----------------------Mac OSX TIPS--------------------------------------
171 When building Blender on OSX you have three choices:
172 METHOD 1. Build using the old NaN Makefiles.
173 METHOD 2. Build using the new automake/autoconf files
174 METHOD 3. Use the Project Builder project
175
176 METHOD 1 and 3
177 The first 4 steps are th same for methods 1 and 3. Only the actual Blender 
178 build step number 5 is different.
179
180 Step1:
181 If you want to follow method 1 and 3, follow the instructions above to set the
182 environment variables. You don't need to edit the Makefiles. They should work
183 out of the box in combinations with some external libraries that should be on
184 your system in a fixed location. 
185
186 Step 2:
187 You can use the package installer fink (http://fink.sourceforge.net/) for some
188 of the external libraries:
189 1. jpeg    (fink install libjpeg)
190 2. png     (fink install libpng3)
191 3. cvs     (fixes some bugs in the shipped cvs: fink install cvs)
192 4. python22 ((addes the static lib for python) fink install python22)
193         You will probably want to select python-nox when
194         it asks you.
195 5. freetype (fink install freetype2)
196
197 After you have done this you should install the mx lib from:
198 http://www.egenix.com/files/python/mxTextTools.html
199
200 (we are currently in the process removing mxTextTools from Blender)
201
202 Step 3:
203 The rest of the external libraries are present in CVS in binary format so you
204 don't have to download them. Precompiled libraries are found in CVS in 
205 directory:
206 $NANBLENDERHOME/lib/darwin-6.1-powerpc
207 If you are not running on a darwing kernel 6.1 (which is likely if you auto-
208 update your system, you might want to add a symbolic link in the 
209 $NANBLENDERHOME/lib/ directory. For example, if you work on a 6.2 kernel:
210 ln -s darwin-6.1-powerpc darwin-6.2-powerpc
211
212 Step 4: 
213 Start the build process by building Blender's "intern" libraries. Navigate to 
214 $NANBLENDERHOME/intern and type make. This will build the intern libaries which
215 will be installed into the $NANBLENDERHOME/lib/darwin-6.1-powerpc (thanks to 
216 the symbolic link).
217 Now you can choose how to build Blender itself; using the Makefiles or the 
218 Project Builder project.
219
220 Step 5 METHOD 1:
221 Navigate to $NANBLENDERHOME/source and type make. 
222
223 Step 5 METHOD 3:
224 The project Builder project can be found in the directory:
225 $NANBLENDERHOME/projectfiles/pb_2_0_1
226 Start Project Builder open the blender.pbproj project, choose a target (blender
227 or player) and build.
228
229 Step 6:
230 Although the Makefiles in the intern directory run ranlib on the libraries 
231 built, the gcc linker complains about ranlib not being run. Until there is a
232 solution, you will need to run ranlib by hand once in a while when the make 
233 breaks. Luckily, the error message lists the full path of the file to run 
234 ranlib on... Anybody out there with a real solution? I guess the problem arises
235 from copying the files from one location to the other...
236
237
238 BUILDING EXTERNAL LIBRARIES
239 If you don't want to use the precompiled libraries you can download and/or
240 build them yourself. Here are some directions.
241
242 PYTHON:
243 Mac OSX 10.2 (Jaguar) now comes with Python (2.2.1) pre-installed. This is fine
244 for producing the "frozen" Python code found in the intern directory. However,
245 the installation does not contain the python library to link against (at least
246 I could not find it). You could use fink to install Python but that Python 
247 installation depends on X being installed and that is a large installation.
248
249 If you prefer the easy way: download Python 2.2.2 from http://www.python.org.
250 Follow the instructions to in the documentation to install it on your box. If
251 you run OSX 10.2 it should install just fine. Basically a configure and a 
252 "make" will do the job. The result is a Python library that should be copied to
253 the library tree together with the associated header files.
254
255 Create the following  directories:
256 $NANBLENDERHOME/lib/darwin-6.1-powerpc/python/include/python2.2
257 $NANBLENDERHOME/lib/darwin-6.1-powerpc/python/lib/python2.2/config
258 Now copy the include files and the libpython2.2.a library to those locations.
259
260 ODE:
261 Ode is currently included in the source tree of Blender. This might change in
262 the close future. But for now you don't need to download Ode.
263 If you want to build ODE yourself, you'll have to edit a config file of ODE first.
264 go to $NANBLENDERHOME/extern/ode/dist/config and edit the file "user-settings" so 
265 that platform is equal to osx (PLATFORM=osx).
266
267 QUICKTIME:
268 In order to compile Blender with QuickTime support enabled, you need to have the 
269 QuickTime 6 SDK installed (see http://developer.apple.com/quicktime/). This extra
270 step is only necessary if you're using a version of MacOS X prior to 10.2.
271 When using the new automake system, QuickTime support can be enabled by passing
272 the "--enable-quicktime=yes" flag to ./configure. When building with the original 
273 NaN Makefiles, QuickTime support is enabled automatically.
274 ----------------------NetBSD TIPS--------------------------------------
275 NetBSD (and other platforms using pkgsrc)
276
277 Quick Install
278
279 cd /usr/pkgsrc/graphics/blender
280 make install
281
282 In-depth Instructions
283
284 NetBSD's Packages Collection provides for easy installation from 
285 source on a multitude of platforms (NetBSD, Linux, OpenBSD, FreeBSD, 
286 Darwin, Irix).  You should be able to compile and install Blender 
287 easily by simply changing into the directory 
288 /usr/pkgsrc/graphics/blender and issuing the command 'make install'.  
289 This will automatically download the sources, verify their integrity, 
290 download and install all necessary dependencies and build and install 
291 Blender.  Please see for details:
292         http://www.netbsd.org/Documentation/software/packages.html
293         http://www.netbsd.org/Documentation/pkgsrc/
294
295
296 Note that there are a few flags you can set to compile in support for 
297 additional packages.  Search /usr/pkgsrc/mk/bsd.pkg.defaults.mk for 
298 "BLENDER" variables and set them according to your preference in 
299 /etc/mk.conf
300
301 If you experience problems building the package, please use send-pr(1)
302
303 on your NetBSD system or submit a proble report via:
304  http://www.netbsd.org/cgi-bin/sendpr.cgi?gndb=netbsd