8aa30757a89c57a96f67e91a197c313c297d3b06
[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 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 For the translations to other languages than English you will need gettext,
32 freetype2 and FTGL. Note that these translations are not complete yet, some
33 time after the release of 2.27 they will be made available for download also.
34 We welcome feedback about the translated user interface, and even contributions
35 to the translation effort :)
36
37 gettext:     http://www.gnu.org/software/gettext/
38 freetype2:   http://www.freetype.org/
39 FTGL:        http://homepages.paradise.net.nz/henryj/code/#FTGL
40
41 FTGL needs a small patch to get glyphs with the right colour in the cache
42 --- FTGL/src/FTPixmapGlyph.cpp.orig     2003-05-10 16:07:45.000000000 +0200
43 +++ FTGL/src/FTPixmapGlyph.cpp  2003-05-10 16:09:19.000000000 +0200
44 @@ -33,3 +33,3 @@
45          // Get the current glColor.
46          float ftglColour[4];
47 -        glGetFloatv( GL_CURRENT_COLOR, ftglColour);
48 +        ftglColour[0] = ftglColour[1] = ftglColour[2] = ftglColour[3] = 1.0;
49
50
51 *********************************************************************
52 *********************************************************************
53 We are in the process of moving things over to automake/autoconf
54 The old makefiles are still in place and will work.  
55 If you want to get a working blender skip down to the next section 
56 and use this readme as a guide.
57
58 If you want to play with the new autoconf environment take a look at 
59 doc/autoconfig.txt
60
61 *********************************************************************
62 *********************************************************************
63
64 --Notes on compiling mxTextTools----------------------------------------------
65 To get the latest version to compile on my machine I had to
66 edit mxSetup.py and remove /usr/include from INCLPATH for it to build
67 properly.
68 (after doing this you need to edit blender/source/Makefile and
69 fix the pointer to it I'm still working on automating this)
70
71 --------------Basic Makefile TIPS---------------------------------------
72 Edit source/nan_definitions.mk to fit your environment, be sure to edit the
73 block matching your OS. You will want to change variables like NAN_OPENSSL,
74 NAN_JPEG, NAN_PNG etc. to point to where you have those installed.
75
76 If you want to integrate the game-engine in Blender, you might want
77 to uncomment the following line in nan_compile.mk:
78 #CFLAGS += -DGAMEBLENDER=1
79 The define is disabled by default because there are still some
80 problems with this at the moment.
81
82 After adjusting things for your environment run 'make' (or use the nice hmake
83 script at blender/source/tools/hmake/hmake)
84
85 ----------------------WINDOWS TIPS--------------------------------------
86
87 When building Blender on Windows you have three choices:
88 METHOD 1. Build using the old NaN Makefiles.
89 METHOD 2. Build using the new automake/autoconf files
90 METHOD 3. Use Microsoft Visual Studio project files
91
92 These directions are for method 3. Method 1 was used in Nan in combination 
93 with Cygwin. I don't know if somebody ever tried method 2.
94
95 EXTERNAL LIBARIES
96 All external libraries that Blender depends on are found in CVS in 
97 precompiled form. If you did not already do so, check out 
98 blender/lib/windows from CVS. If you prefer to build or download those 
99 libraries yourself, there are some directions below.
100
101 INTERN LIBRARIES:
102 The first thing you need to do is to build the Blender "intern" libraries.
103 You need to have Python installed on your machine.
104
105 Open the workspace in the $NANBLENDERHOME/intern/make/msvc_6_0 directory.
106 Build the "build_install_all" project. This will build all the intern libraries
107 and installs them in the $NANBLENDERHOME/lib/windows directory.
108
109 If the post build step (copying the libraries to their destinations) fails,
110 this is probably due to the fact that MSVC can't find the XCOPY command as 
111 happened to me on an XP system. MSVC has it's own PATH that you can set through
112 the options. Open options from the menu: Tools->Options. Go to the directories
113 tab and select "Executable files" from the drop down menu. Now add you SYSTEM32
114 directory.
115
116 The last project build is the python_freeze project that will freeze python code
117 for compilation and linking with Blender's C code. At the moment, this should be
118 automatic except that batch file probably does not find Python. If this is the
119 case, follow the same procedure as was mentioned above for the XCOPY command
120 to add Python to your path.
121
122 BUILDING BLENDER
123
124 Open the workspace $NANBLENDERHOME/projectfiles/blender/blender.dsw
125
126 This contains the following three main projects:
127 blender           Builds the main executable
128 GP_ghost          Builds the stand-alone game player
129 GP_axctl          Builds the ActiveX control
130
131 Choose the project you want to build and hit F7. If all is well it should build
132 with a lot of warnings but no errors.
133
134 BUILDING/DOWNLOADING EXTERNAL LIBRARIES
135 If you don't want to use the precompiled libraries you can download and/or
136 build them yourself. Here are some directions.
137
138 JPEG:
139 BINARY LIBRARY:
140 Go to sourceforge.net, navigate to the GnuWin32 project and download 
141 libjpeg-6b-lib.zip. Rename the unzipped directory "jpeg" and copy it to the 
142 $NANBLENDERHOME/lib/windows directory.
143 FROM SOURCES:
144 Download the jpeg sources from http://www.ijg.org/. Go into the source 
145 directory and copy the file jconfig.vc to jconfig.h. Now start a command box
146 and run nmake /f makefile.vc (assuming nmake is in your path, if not run the
147 vcvars32.bat batch file located in the VC98/Bin directory of the MSVC 
148 installation directory first).
149 Copy these include files: jconfig.h, jerror.h, jmorecfg.h, jpeglib.h
150 from the build directory to the lib tree in this directory:
151 $NANBLENDERHOME/lib/windows/jpeg/include
152 The file libjpeg.lib should be copied to:
153 $NANBLENDERHOME/lib/windows/jpeg/lib
154
155 PNG:
156 Go to sourceforge.net, navigate to the GnuWin32 project and download 
157 libpng-1.2.4-1-lib.zip. Rename the unzipped directory "png" and copy it to the 
158 $NANBLENDERHOME/lib/windows directory.
159
160 ZLIB:
161 Go to sourceforge.net, navigate to the GnuWin32 project and download 
162 zlib-1.1.4-lib.zip. Rename the unzipped directory "zlib" and copy it to the 
163 $NANBLENDERHOME/lib/windows directory.
164
165
166 ----------------------Mac OSX TIPS--------------------------------------
167 When building Blender on OSX you have three choices:
168 METHOD 1. Build using the old NaN Makefiles.
169 METHOD 2. Build using the new automake/autoconf files
170 METHOD 3. Use the Project Builder project
171
172 METHOD 1 and 3
173 The first 4 steps are th same for methods 1 and 3. Only the actual Blender 
174 build step number 5 is different.
175
176 Step1:
177 If you want to follow method 1 and 3, follow the instructions above to set the
178 environment variables. You don't need to edit the Makefiles. They should work
179 out of the box in combinations with some external libraries that should be on
180 your system in a fixed location. 
181
182 Step 2:
183 You can use the package installer fink (http://fink.sourceforge.net/) for some
184 of the external libraries:
185 1. openssl (fink install openssl)
186 2. openssl-dev (fink install openssl-dev)
187 3. jpeg    (fink install libjpeg)
188 4. png     (fink install libpng)
189 5. cvs     (fixes some bugs in the shipped cvs: fink install cvs)
190 6. python22 ((addes the static lib for python) fink install python22)
191         You will probably want to select python22-nox-shlibs when
192         it asks you.
193
194         After you have done this you should install the mx lib from:
195         http://www.egenix.com/files/python/mxTextTools.html
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 PYTHON:
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 ODE:
256 Ode is currently included in the source tree of Blender. This might change in
257 the close future. But for now you don't need to download Ode.
258 If you want to build ODE yourself, you'll have to edit a config file of ODE first.
259 go to $NANBLENDERHOME/extern/ode/dist/config and edit the file "user-settings" so 
260 that platform is equal to osx (PLATFORM=osx).
261
262 QUICKTIME:
263 In order to compile Blender with QuickTime support enabled, you need to have the 
264 QuickTime 6 SDK installed (see http://developer.apple.com/quicktime/). This extra
265 step is only necessary if you're using a version of MacOS X prior to 10.2.
266 When using the new automake system, QuickTime support can be enabled by passing
267 the "--enable-quicktime=yes" flag to ./configure. When building with the original 
268 NaN Makefiles, QuickTime support is enabled automatically.