diff options
Diffstat (limited to 'dev/MinGfx/docs/html/installation.html')
| -rw-r--r-- | dev/MinGfx/docs/html/installation.html | 206 |
1 files changed, 206 insertions, 0 deletions
diff --git a/dev/MinGfx/docs/html/installation.html b/dev/MinGfx/docs/html/installation.html new file mode 100644 index 0000000..f7660d5 --- /dev/null +++ b/dev/MinGfx/docs/html/installation.html @@ -0,0 +1,206 @@ +<!-- HTML header for doxygen 1.8.9.1--> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> +<meta http-equiv="X-UA-Compatible" content="IE=9"/> +<meta name="generator" content="Doxygen 1.9.1"/> +<title>MinGfx Toolkit: Installation Guide</title> +<link href="tabs.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="jquery.js"></script> +<script type="text/javascript" src="dynsections.js"></script> +<link href="search/search.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="search/searchdata.js"></script> +<script type="text/javascript" src="search/search.js"></script> +<script type="text/x-mathjax-config"> + MathJax.Hub.Config({ + extensions: ["tex2jax.js"], + jax: ["input/TeX","output/HTML-CSS"], +}); +</script> +<script type="text/javascript" async="async" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js"></script> +<link href="doxygen.css" rel="stylesheet" type="text/css" /> +<link href="customdoxygen.css" rel="stylesheet" type="text/css"/> +</head> +<body> +<div id="top"><!-- do not remove this div, it is closed by doxygen! --> +<div id="titlearea"> +<table cellspacing="0" cellpadding="0"> + <tbody> + <tr style="height: 56px;"> + <td style="padding-left: 0.5em;"> + <div id="projectname">MinGfx Toolkit +  <span id="projectnumber">1.0</span> + </div> + <div id="projectbrief">A minimal library for writing cross-platform (Windows, OSX, linux) graphics programs.</div> + </td> + </tr> + </tbody> +</table> +</div> +<!-- end header part --> +<!-- Generated by Doxygen 1.9.1 --> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ +var searchBox = new SearchBox("searchBox", "search",false,'Search','.html'); +/* @license-end */ +</script> +<script type="text/javascript" src="menudata.js"></script> +<script type="text/javascript" src="menu.js"></script> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ +$(function() { + initMenu('',true,false,'search.php','Search'); + $(document).ready(function() { init_search(); }); +}); +/* @license-end */</script> +<div id="main-nav"></div> +<!-- window showing the filter options --> +<div id="MSearchSelectWindow" + onmouseover="return searchBox.OnSearchSelectShow()" + onmouseout="return searchBox.OnSearchSelectHide()" + onkeydown="return searchBox.OnSearchSelectKey(event)"> +</div> + +<!-- iframe showing the search results (closed by default) --> +<div id="MSearchResultsWindow"> +<iframe src="javascript:void(0)" frameborder="0" + name="MSearchResults" id="MSearchResults"> +</iframe> +</div> + +</div><!-- top --> +<div class="PageDoc"><div class="header"> + <div class="headertitle"> +<div class="title">Installation Guide </div> </div> +</div><!--header--> +<div class="contents"> +<div class="textblock"><p><a class="anchor" id="md_doc_installation"></a></p> +<h1><a class="anchor" id="install-prereqs"></a> +Prereqs</h1> +<p>MinGfx is built using the cross-platform CMake tool. Before building MinGfx, you will need to install CMake version 3.9 or higher (<a href="https://cmake.org/">https://cmake.org/</a>). On Mac, you will need to have Xcode installed as well as the <a href="https://www.embarcadero.com/starthere/xe5/mobdevsetup/ios/en/installing_the_commandline_tools.html">optional Xcode command line tools</a>.</p> +<p>If you haven't already, you'll want to clone the MinGfx source code using git, so make sure you have git installed as well.</p> +<h1><a class="anchor" id="cmake-background"></a> +Background for CMake Beginners</h1> +<p>If you are new to CMake, this is the minimum background you should have before building MinGfx.</p> +<p>CMake is a cross-platform tool for generating native Unix Makefiles and project workspaces (e.g., Xcode projects, Visual Studio solutions) for building projects. Projects use CMakeLists.txt files to describe how they should be built. These files provide input for the cmake application, which uses them to generate project files for a variety of development environments. CMake can generate Makefiles for building MinGfx on linux systems or project files for building MinGfx with popular IDEs (e.g., XCode, Visual Studio, Eclipse, CodeBLocks). <br /> +</p> +<p>There are three versions of the cmake application that are provided with the install from Kitware. You can use any of these with MinGfx:</p><ol type="1"> +<li><em>cmake</em> is the command line version where all build options must be specified on the command line.</li> +<li><em>ccmake</em> is a visual interface that runs in a terminal. This is nice because all of the available build options are listed for you to see at once, and you can simply press the SPACEBAR to turn them on/off or type in specific values. The downside for ccmake is that it does not have a separate log window, so status messages flash by so fast that you cannot read them, and input from spin-off cmake processes (like those used in the MinGfx configure step) are not captured correctly. It's possible to still use ccmake with MinGfx, but we do not recommend it.</li> +<li><em>cmake-gui</em> is an OS-specific windowed version. Like ccmake, the GUI provides a useful list all of the available build options. Unlike ccmake, it also includes a nice scrollable log of all of the status messages. So, this is the preferred version for new users and for the first time you build a project.</li> +</ol> +<p>With CMake, it's best to do an out-of-source build. That means that when you start CMake you must tell it two paths: 1. the path to the MinGfx source tree, AND 2. the path to the place where you would like all the built files to be created. When running cmake-gui, these can be set interactively with a file selection dialog, but all three versions respond to command line options, and this is generally the easiest way to start up cmake. So, we suggest starting <em>cmake-gui</em> from the command line. First cd to the directory you wish to use for the built files, then pass a single required command line argument for the path to the MinGfx source tree. Usually, you will see this written as a series of 3 steps – the common idiom for cmake builds: </p><div class="fragment"><div class="line">// from within the root of the project's source directory</div> +<div class="line">mkdir build</div> +<div class="line">cd build</div> +<div class="line">cmake-gui ..</div> +</div><!-- fragment --><p>If you are using <em>cmake</em> you can pass a variety of other options to CMake on the command line with flags such as -D AUTOBUILD_NANOGUI=ON, to tell MinGfx to autobuild the nanogui library that it depends upon. With <em>cmake</em>, you can end up with a long string of arguments in order to setup the build you want. With <em>cmake-gui</em>, you set all of these build options within the user interface instead, and this is how we will proceed in the instructions that follow.</p> +<h1><a class="anchor" id="build-tree"></a> +Setup a New Graphics Build Tree</h1> +<p>Here's a complete annotated list of steps to setup a new build tree for creating graphics programs. In truth, you don't need to create this entire build tree strucutre just to work with MinGfx, but this is good practice, and a good guide for students.</p> +<h2><a class="anchor" id="autotoc_md2"></a> +1. Create a Linux-Style Directory Tree</h2> +<p>Libraries will get installed to a lib/ directory. Include files will go in include/, executables in bin/, and we'll put the source we are developing inside dev/.</p> +<div class="fragment"><div class="line">mkdir -p /Users/keefe/courses/csci4611/sw</div> +<div class="line">cd /Users/courses/csci4611/sw</div> +<div class="line">mkdir lib</div> +<div class="line">mkdir include</div> +<div class="line">mkdir bin</div> +<div class="line">mkdir dev</div> +</div><!-- fragment --><p>IMPORTANT: On Windows, you will need to add the <code>bin</code> directory you just created to your PATH environment variable. If you have not done this before, you will find many instructions online. Here is one good description of <a href="https://www.java.com/en/download/help/path.xml">how to add a directory to the PATH environment variable on Windows</a>.</p> +<h2><a class="anchor" id="autotoc_md3"></a> +2. Download the MinGfx Project</h2> +<p>To download use: </p><div class="fragment"><div class="line">cd dev</div> +<div class="line">git clone http://github.com/ivlab/MinGfx</div> +</div><!-- fragment --><h2><a class="anchor" id="autotoc_md4"></a> +3. Create an Initial CMake Build Configuration</h2> +<div class="fragment"><div class="line">cd MinGfx</div> +<div class="line">mkdir build</div> +<div class="line">cd build</div> +<div class="line">cmake-gui ..</div> +</div><!-- fragment --><p>Press the 'Configure' button. Then, select the Generator you would like to use from the list provided (e.g., Xcode, Visual Studio, Unix Makefiles). Click Done.</p> +<p>Wait for CMake to do an initial configuration. This will populate an initial list of CMake and MinGfx build options. Each time you run configure, <em>cmake-gui</em> will display any new configuration options highlighted in <em>red</em>. So, do not be alarmed when the whole options window turns red during this first configure operation – that is normal behavior since at this point, all of the options are new.</p> +<p>Do you see an error in the CMake output window? If so, don't worry about this yet, we'll come back to it in a minute.</p> +<h2><a class="anchor" id="autotoc_md5"></a> +4. Set the CMAKE_INSTALL_PREFIX Variable to the Root of Your Directory Tree</h2> +<p>Now, using cmake-gui, scroll through the table of variables until you find the one named CMAKE_INSTALL_PREFIX. Click on it and edit its value to point to the root of the directory tree you created in Step 1. The root for the example tree used in Step 1 would be /Users/keefe/courses/csci4611/sw. In other words, the root is the last directory before you get to lib, include, bin, and dev.</p> +<p>Once you make this change, you can press the Configure button again. It doesn't hurt to press Configure multiple times. You need to do it at least once after every change you make. Notice how the variables highlighted in red go away when you do this because they are no longer new options – cmake knows that you have already had a chance to see them once.</p> +<h2><a class="anchor" id="autotoc_md6"></a> +5. If Needed, Set AUTOBUILD_NANOGUI to ON and Build Dependencies</h2> +<p>Now, take a look at the output window at the bottom of cmake-gui. If you see the following error there, then we'll address that next. If not, then nanogui must already be installed on your system, and you can skip to step 6. </p><div class="fragment"><div class="line">Searching for NanoGUI library...</div> +<div class="line">Could NOT find NANOGUI (missing: NANOGUI_LIBRARIES)</div> +<div class="line">CMake Error at cmake/UseNanoGUI.cmake:96 (message):</div> +<div class="line">The NanoGUI library was not found on the system. You can: (1) install</div> +<div class="line">NanoGUI yourself, (2) point cmake to an already-installed version of</div> +<div class="line">NanoGUI by adding the installation prefix of NanoGUI to the</div> +<div class="line">CMAKE_PREFIX_PATH environment variable, or (3) set AUTOBUILD_NANOGUI to ON</div> +<div class="line">and run cmake configure again. AUTOBUILD_NANOGUI will: 1. download</div> +<div class="line">NanoGUI, 2. build NanoGUI, and 3. install NanoGUI to the</div> +<div class="line">CMAKE_INSTALL_PREFIX (currently set to</div> +<div class="line">/Users/keefe/courses/tmp/MinGfx/build/install). If you want to use the</div> +<div class="line">AUTOBUILD feature, adjust CMAKE_INSTALL_PREFIX as desired now, set</div> +<div class="line">AUTOBUILD_NANOGUI to ON, and then run cmake configure again.</div> +<div class="line">Call Stack (most recent call first):</div> +<div class="line">src/CMakeLists.txt:80 (UseNanoGUI)</div> +<div class="line">CMakeLists.txt:186 (include)</div> +</div><!-- fragment --><p> This error tells us that cmake could not find the nanogui library pre-installed on our system. Luckily, MinGfx includes support for downloading, building, and installing nanogui for you using the AUTOBUILD_NANOGUI feature.</p> +<p>Scroll through the list of CMake variables again until you find AUTOBUILD_NANOGUI and click on the checkbox next to it to turn it on. Now, click Configure again. This time the configure step will take a while, perhaps 5 minutes, to run because it will be downloading, building, and installing nanogui and all of its dependencies. <br /> +</p> +<p>This step should finish without an error. If you do see an error and you are working with this as part of a UMN course, you may need to stop now and ask for help from a TA or on the class forum – perhaps there is something we haven't planned for in the particular setup of your computer.</p> +<h2><a class="anchor" id="autotoc_md7"></a> +6. Generate the Build System / Project Files</h2> +<p>Finally, you are ready to press the Generate button. This is the step that will actually generate the Unix Makefiles, Visual Studio Solution File, or Xcode Project File needed to build MinGfx. <br /> +</p> +<h2><a class="anchor" id="autotoc_md8"></a> +7. Build MinGfx with the Specified Options</h2> +<p>Click Open Project if you generated project files for an IDE, or if you generated Unix Makefiles return to your shell and the build directory. Now, build the project as you normally would in these enviornments. <br /> +</p> +<p>For Xcode: <code>click the Triangle button to build the ALL_BUILD target</code></p> +<p>For Visual Studio: In the Solution Explorer Window <code>right click on ALL_BUILD</code> and select <code>Build</code></p> +<p>For Unix Makefiles: run <code>make all</code>.</p> +<h2><a class="anchor" id="autotoc_md9"></a> +8. Install the Library to your Directory Tree</h2> +<p>For Xcode: <code>click on ALL_BUILD to reveal a dropdown list and select install</code> then <code>click the Triangle button</code></p> +<p>For Visual Studio: In the Solution Explorer Window <code>right click on INSTALL</code> and select <code>Build</code>.</p> +<p>For Unix Makefiles: run <code>make install</code>.</p> +<p>To see if it worked take a look in the lib, include, and bin directories within the root of the tree you setup in Step 1. You should see the test programs inside bin/ and folders for MinVR-1.0 inside lib/ and include/.</p> +<h2><a class="anchor" id="autotoc_md10"></a> +9. Run a Test Program</h2> +<p>For Xcode: <code>click on ALL_BUILD to reveal a dropdown list and select mingfx-test-gui-plus-opengl</code> then <code>click the Triangle button</code></p> +<p>For Visual Studio: In the Solution Explorer Window <code>right click on mingfx-test-gui-plus-opengl</code> then selece <code>Set as StartUp Project</code>. Now, <code>click the green triangle button to run the program</code>. IMPORTANT NOTE: When the program runs it will need to find some .dlls that were installed to your <code>bin</code> directory in Step 8. So, the bin directory <em>must be in your windows PATH</em>. If you skipped this part of Step 1, go back and add <code>bin</code> to your PATH environment variable now. Then, you may need to restart Visual Studio for it to recognize the new setting.</p> +<p>For Unix Makefiles: from within the build directory run: <code>tests/mingfx-gui-plus-opengl</code></p> +<h1><a class="anchor" id="example"></a> +Create Your Own Graphics Program</h1> +<p><em>Prereq:</em> Before getting started, make sure you have installed MinGfx, going all the way through the 9th step above.</p> +<p>The project in the MinGfx/example folder is an example of a stand-alone project that uses a separate cmake build system. This means we can copy it and move it out of the MinGfx source tree to serve as a starting point for your own project. Let's do that now.</p> +<div class="fragment"><div class="line">cd /Users/courses/csci4611/sw/dev (or wherever you put your dev directory)</div> +<div class="line">cp -r MinGfx/example/ mingfx-example</div> +</div><!-- fragment --><p>Now, before we build the example, we need to make sure it knows where to find MinGfx. <br /> + </p><div class="fragment"><div class="line">cd mingfx-example</div> +<div class="line">open up the CMakeLists.txt file in your favorite text editor</div> +</div><!-- fragment --><p>Near the top of the file, find the following lines </p><div class="fragment"><div class="line"># !!!!!!!!!!!!! EDIT THE FOLLOWING LINE AS NEEDED !!!!!!!!!!!!! </div> +<div class="line">list(APPEND CMAKE_PREFIX_PATH ${CMAKE_CURRENT_SOURCE_DIR}/../build/install ../../..)</div> +</div><!-- fragment --><p> and add a path to the end of the list to point to the ROOT of your directory tree, for example: </p><div class="fragment"><div class="line"># !!!!!!!!!!!!! EDIT THE FOLLOWING LINE AS NEEDED !!!!!!!!!!!!! </div> +<div class="line">list(APPEND CMAKE_PREFIX_PATH ${CMAKE_CURRENT_SOURCE_DIR}/../build/install ../../.. /Users/keefe/courses/cs4611/sw)</div> +</div><!-- fragment --><p>Now, we're ready to build this example using the same cmake idiom as before: </p><div class="fragment"><div class="line">mkdir build</div> +<div class="line">cd build</div> +<div class="line">cmake-gui ..</div> +</div><!-- fragment --><p> Then, click <em>Configure</em>. If you want to install this example program, you may now edit the CMAKE_INSTALL_PREFIX as before and rerun <em>Configure</em>. It should not be necessary to change any of the other cmake variables for this example program.</p> +<p>Next, click <em>Generate</em> to produce project files for your IDE or makefiles. <br /> +</p> +<p>Next, build the example program within your IDE or by running <code>make</code>.</p> +<p>Finally, you can run your first example graphics program with the command: </p><div class="fragment"><div class="line">./mingfx-example</div> +</div><!-- fragment --><p>You can change the name of the executable, add more header and source files to the project and make other changes to the build process by editing the CMakeLists.txt file, but remember that after each change, you must run CMake's <em>Configure</em> and <em>Generate</em> steps again. <br /> +</p> +<p>To reiterate the point above, if you are using an IDE, it is important to remember to add new files to your project by editing the CMakeLists.txt file NOT by using File->Add To Project.. or whatever option is provided inside your IDE. Since we using CMake to generate the IDE's project files, and we may want to switch to a different IDE or to Makefiles in the future, the CMakeLists.txt file needs to be treated as the master record of all of the build settings. </p> +</div></div><!-- contents --> +</div><!-- PageDoc --> +<!-- HTML footer for doxygen 1.8.9.1--> +<!-- start footer part --> +<hr class="footer"/><address class="footer"><small> +Generated by  <a href="http://www.doxygen.org/index.html"> +<img class="footer" src="doxygen.png" alt="doxygen"/> +</a> 1.9.1 +</small></address> +</body> +</html> |