TMV Build Guide
This is the build guide for the TMV code base
Note: This initial version is targeted only at windows platforms using Visual Studio 2005. I'm going to assume you are reasonably comfortable using Visual Studio 2005.
Windows Platforms (XP & Vista)
Building Existing Code
- Step 1: Get the appropriate 3rd party software, see the environment page for more details.
- At a minimum
- You need Visual Studio 2005 for development & debugging
- You need Subversion for version control of the source code repository
- Step 2: Download the latest code from the repository using Subversion.
- Step 3: Build the API libraries
- Let's assume that you downloaded the main trunk of source code to c:\TMV_Main
- Go to the API's main project, found at c:\TMV_Main\apis\projects\TMV_Apis
- Launch the VS2005 solution "TMV_Apis.sln"
- Launch the "Configuration Manager" for the project
- Pick your build environment
Debug vs. Release
Win32 vs. x64
-
- Build the project from the build menu which should build all the apis
- Step 4: Build Your Tools (or apps)
- Note: If you haven't build the appropriate libraries first, you won't be able to build the tools...
- Go to the API's main project, found at c:\TMV_Main\tools\projects\TMV_Tools
- the apps main project is found in c:\TMV_Main\apps\projects\TMV
- Launch the VS2005 solution "TMV_Tools.sln" (or "TMV.sln" for apps)
- Launch the "Configuration Manager" for the project
- Pick your build environment
4 possiblities:
Debug vs. Release
Win32 vs. x64
-
- Build the project from the build menu which should build all the tools (or apps)
- Step 5: Fix up the OpenGL viewer tools for your platform
- Chances are quite good that all the viewer tools won't build properly
- This is because they are all dependent on OpenGL
- To build OpenGL properly, you need the correct libraries and include files for your platform
Windows XP, Win32
Windows XP, Win64
Windows Vista, Win32
Windows Vista, Win64
-
- You will need to update all the include paths and library paths for each project to point to the correct OpenGL includes and libraries
- We have default OpenGL includes, libraries, and binaries checked into our tree (or you are free to use your own)
- Our OpenGL libraries are located at the following place in the API tree
Windows XP, Win32
.\apis\OpenGL\XP\x32\DLL
.\apis\OpenGL\XP\x32\include
.\apis\OpenGL\XP\x32\lib
Windows XP, Win64
.\apis\OpenGL\XP\x64\DLL
.\apis\OpenGL\XP\x64\include
.\apis\OpenGL\XP\x64\lib
Windows Vista, Win32
.\apis\OpenGL\Vista\x32\DLL
.\apis\OpenGL\Vista\x32\include
.\apis\OpenGL\Vista\x32\lib
Windows Vista, Win64
.\apis\OpenGL\Vista\x64\DLL
.\apis\OpenGL\Vista\x64\include
.\apis\OpenGL\Vista\x64\lib
-
- Note: I haven't been able to figure this out yet
- sometimes relative paths work just fine in VS2005
..\..\..\apis\OpenGL\Vista\x32\include
..\..\..\apis\OpenGL\Vista\x32\lib
-
-
- othertimes, you need to use absolute paths to get it to work properly
c:\TMV_Main\apis\OpenGL\Vista\x32\include
c:\TMV_Main\apis\OpenGL\Vista\x32\lib
-
- Note: For the viewers to run properly after building
They need to be able to find the OpenGL Dll's
- The easist soluton is to just copy all 3 dll's into the same directory as your executable.
New Tools (and apps)
- Where should I store my new application?
- The 'tools' directory, intended for useful tools
- tool is useful & used regularly.
- tool has a single purpose or a group of closely aligned purposes (viewing, filtering, compression, smoothing, etc.).
- tool is used by more people than just yourself.
- The 'apps' directory, intended for idea creation
- Scratch space
- Modifying or hacking an existing tool to test out a new idea
- Brand new unexplored ideas
- Merging a variety of different concepts
- If your application is a one-shot tool for a single temporary purpose
- Directory Structure
- Each application or tool should have the following base directory layout
- .\inc - intended to store local include files (*.h) used by the tool or app
- .\src - intended to store local source files (*.cpp) used by the tool or app
- .\projects - intended to store Visual Studio 2005 project files that describe how to build or make your tool (or app).
Creating a new Tool or Application by copying an existing tool (or app)
- Copy an existing good application
- It's usually easier to use another tool (or app) as a starting point for your new tool (or app)
- the tool 'spdiff' is a good default starting point for 'Streaming Point' apps
- the tool 'smsmooth' is a good default starting point for 'Streaming Mesh' apps
- In the following step by step guide, assume I'm creating a new app called 'foo' based on the existing tool 'smsooth'
- Step 1: Create a new base directory layout
cd c:\TMV_Main\apps
mkdir foo
cd foo
mkdir inc
mkdir src
mkdir projects
which creates
.\apps\foo
.\apps\foo\inc
.\apps\foo\src
.\apps\foo\projects
- Step 2: Copy an existing starting project
- if I picked 'smsmooth' as a starting point
cd c:\TMV_Main\apps\foo\projects
copy c:\TMV_Main\tools\smsmooth\projects\smsmooth.sln
copy c:\TMV_Main\tools\smsmooth\projects\smsmooth.vcproj
- Step 3: Copy any local inclues or source files to your directory
cd c:\TMV_Main\apps\foo\inc
copy c:\TMV_Main\tools\smsmooth\inc\*.h
cd c:\TMV_Main\apps\foo\src
copy c:\TMV_Main\tools\smsmooth\src\*.cpp
- Step 4: Rename local source files for your app, as appropriate
Note: Keep track of any files you rename for later reference
cd c:\TMV_Main\apps\foo\inc
rename smsmooth.h foo.h
cd c:\TMV_Main\apps\foo\src
rename smsmooth.cpp foo.cpp
- Step 5: Rename starting project DOS names to our project name
cd c:\TMV_Main\apps\foo\projects
rename smsmooth.sln foo.sln
rename smsmooth.vcproj foo.vcproj
- Step 6: Rename the VS2005 starting project name to our project name
- Launch VS2005
- Attempt to load the solution file 'foo.sln'
- VS2005 should give you a couple of errors about the project smsmooth.vcproj missing from the solution
- Ignore or skip past these errors
- Remove project smsmooth.vcproj from the solution
- In the 'solution explorer' tab or window, right click on the smsmooth.vcproj
- in the resulting context menu, choose the remove option
- Add back in the renamed project foo.vcproj to the solution
- From the main 'file' menu in VS2005
- click on the 'file\add\existing project' menu path
- In the resulting dialog, find and add 'foo.vcproj' to the solution
- Note: foo.vcproj will show up with the incorrect name 'smsmooth' in the 'solution explorer' tab
- right click on the 'smsmooth' project in the 'solution explorer' tab
- pick the 'rename' option in the popup context menu
- rename the project to our project name 'foo'
- Step 7: Exchange renamed local files into our 'foo' project
- In solution explorer under the 'foo' project
- Open up the 'Header Files' section (IE include directory) and remove any local include files you have renamed.
- Add back in any renamed local include file(s) in the '.\foo\inc' directory.
- Open up the 'Source Files' section (IE source directory) and remove any local source files you have renamed.
- Add back in any renamed local source file(s) in the '.\foo\src' directory
- Step 8: Book keeping changes in project "Property Pages"
- 'In solution explorer', right click on the 'foo' project
- in the resulting context menu, choose 'properties'
- this brings up the Project "Foo Property Pages" dialog
- Double check that the 'include' path(s) in the 'C++\General' section under the 'Additional Include Directories' field are correct
- Double check that the 'lib' path(s) in the 'Linker\General' section uner the 'Additional Library Directories' field are correct
- Make sure your app gets copied into the correct 'bin' target directory after building.
- Fix the 'Build Events\Post Build Event' section under command line and description to reference 'foo' instead of 'smsmooth'
IE change
Command Line: copy $(TargetDir)\smsmooth.exe ..\..\..\Binaries\binD\Win32\smsmooth.exe
Description: Copy 'smsmooth' to BinD
to
Command Line: copy $(TargetDir)\foo.exe ..\..\..\Binaries\binD\Win32\foo.exe
Description: Copy 'foo' to BinD
-
- Note: These change will have to be repeated 4 times, once for each build enviornment
Debug Win32
Release Win32
Debug Win64
Release Win64
- Step 9: You are ready to start building and coding your own 'foo' application
- Question: That was a lot of work and jumping thru hoops, why did we do all that extra busy work?
- Answer: Because it's a lot less work than building a new app from scratch
- If you build a new app from scratch
- You end up wasting a lot of time trying to figure out how to setup all the arcane compiler and linker settings so your app builds correctly.
- Finally, you revert back to opening up 2 sessions of VS2005 and comparing project properties line by line between your non-working 'foo' project and a working project like 'smsmooth'.
- Trying to figure out which missing include path, library path, or some other arcane compiler/linker setting is preventing your project from building.
- Copying an existing app picks up all the correct compiler settings by default.
- Question: Why not use the "New \ Project from Existing Code" feature in VS2005?
- Answer: As far as I can tell, this feature only copies files not compiler settings. If you know different, please let the rest of us know. I would love an easier soluton.
- Question: Why not build a "Custom Project" wizard in Visual Studio?
- Answer: As far as I can tell this feature is only available for C# and Visual Basic in VS2005... If you know how to make it work for C++, we could all benefit from an easier soluton.
The following article makes it sound possible... "Create a Visual C++ Wizard for Visual Studio 2005"
Creating a new Tool or Application by creating it from scratch
!!! Coming Soon !!!
--
ShawnDB - 18 Dec 2008
to top