Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

* Updated Quick Start documentation with the 01-helloworld tutorial.

  • Loading branch information...
commit 79eb65707b9cabd49e23783c3da471739b1a22ec 1 parent f2c44e2
@jjensen jjensen authored
View
61 docs/html/quick_start.html
@@ -6,8 +6,65 @@
</head><body>
<!-- Generated by Doxygen 1.5.7 -->
<div class="contents">
-<h1><a class="anchor" name="quick_start">Quick Start Guide </a></h1></div>
-<hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 29 23:32:26 2008 for JamPlus manual by&nbsp;
+<h1><a class="anchor" name="quick_start">Quick Start Guide </a></h1><h2><a class="anchor" name="quick_start_overview">
+Overview</a></h2>
+JamPlus works out of the box with Visual C++. There is limited MinGW support. Other compiler suites are to come.<p>
+JamPlus generates workspaces for Visual Studio 2003, 2005, and 2008. It can also generate workspaces for CodeBlocks.<p>
+When the Jam executable is run, it reads a file called <code>Jamfile.jam</code> in the current working directory. The Jamfile contains a description of how to build the current project. In the tutorials below, we'll talk about how to properly set up a Jamfile build description.<p>
+<hr>
+ <h2><a class="anchor" name="quick_start_01">
+Tutorial 1: Hello World!</a></h2>
+<h3><a class="anchor" name="quick_start_01_setup">
+Initial Setup</a></h3>
+For this tutorial, we are going to make a basic <b>helloworld</b> application. You will find the source code presented below in the <code>samples/tutorials/01-helloworld/</code> directory in the JamPlus source distribution.<p>
+First, we need to create a basic <code>main.c</code>. It will do nothing more than print <b>Hello, world!</b> to the user.<p>
+<div class="fragment"><pre class="fragment"><span class="comment">/* main.c */</span>
+<span class="preprocessor">#include &lt;stdio.h&gt;</span>
+
+<span class="keywordtype">int</span> main()
+{
+ printf(<span class="stringliteral">"Hello, world!\n"</span>);
+ <span class="keywordflow">return</span> 0;
+}
+</pre></div><p>
+In the same directory as <code>main.c</code>, we need to create <code>Jamfile.jam</code> with the description of how to build the basic <b>helloworld</b> application.<p>
+<div class="fragment"><pre class="fragment"><span class="preprocessor"># This file is Jamfile.jam.</span>
+<span class="preprocessor"></span>SubDir TOP ;
+
+Application helloworld : main.c ;
+</pre></div><h3><a class="anchor" name="quick_start_01_setup">
+Initial Setup</a></h3>
+Compiling the <b>helloworld</b> application is simple. Assuming the Jam executable is in your <code>PATH</code>, run the following from the <code>01-helloworld</code> tutorial directory:<p>
+<div class="fragment"><pre class="fragment">[c:\jamplus\samples\tutorials\01-helloworld]jam
+</pre></div><p>
+That's it. Jam will detect your Visual Studio installation automatically and build the <b>helloworld</b> application's Debug configuration. The resultant filename will be <code>helloworld.debug.exe</code>.<p>
+Building the <b>helloworld</b> application Release configuration is performed with a command line flag. In this case, the built executable will be <code>helloworld.release.exe</code>.<p>
+<div class="fragment"><pre class="fragment">[c:\jamplus\samples\tutorials\01-helloworld]jam -sCONFIG=release
+</pre></div><p>
+This is all well and good if you have one of the Visual Studio compilers, but if you are running with, say, MinGW, an additional command line flag must be provided. MinGW is searched for in the <code>c:/mingw/</code> and <code>d:/mingw/</code> directories.<p>
+<div class="fragment"><pre class="fragment">[c:\jamplus\samples\tutorials\01-helloworld]jam -sCOMPILER=mingw
+</pre></div><h3><a class="anchor" name="quick_start_01_clean">
+Cleaning Up the Tutorial Files</a></h3>
+After a build, you may notice there are a number of extra files in the directory that weren't there before. These are generally compiler intermediates, and we'll soon learn how to redirect them elsewhere.<p>
+For now, instead of leaving behind various junk files, Jam can clean up after itself using the <b>clean</b> target. Targets on the Jam command line are specified after the command line flags. Various examples follow:<p>
+<div class="fragment"><pre class="fragment">rem Cleans the Debug build.
+jam clean
+
+rem Cleans the Debug build, too.
+jam -sCONFIG=debug clean
+
+rem Cleans the Release build, too.
+jam -sCONFIG=release clean
+</pre></div><h3><a class="anchor" name="quick_start_01_workspace">
+Building a Visual Studio Workspace</a></h3>
+One of the exciting aspects of JamPlus is its ability to build Visual Studio workspaces (solutions). It does so with a set of scripts that ship in the JamPlus binary package. These scripts create an out-of-source build tree optimized for best performance within JamPlus. By being out-of-source, the source tree remains pristine.<p>
+For the <b>helloworld</b> application, let's build a Visual Studio 2005 solution using the script <b>JamToWorkspace</b>.<p>
+<div class="fragment"><pre class="fragment">c:\jamplus\bin\scripts\JamToWorkspace --gen=vs2005 Jamfile.jam build
+</pre></div><p>
+In just a quick moment, the new out-of-source work area will have been created. Inside the generated <code>01-helloworld/build/</code> directory, you'll find a <code>helloworld.sln</code>. Open this file in Visual Studio to proceed.<p>
+When Visual Studio has loaded the <code>helloworld.sln</code>, you'll find it contains the <b>helloworld</b> project within the Solution Explorer. If the <b>helloworld</b> project is not already the active project, right click on it and choose <b>Set as StartUp Project</b>.<p>
+At this point, build as you normally would. Change between the Debug and Release configurations if you'd like. In fact, you can even debug as if the project were manually created! </div>
+<hr size="1"><address style="text-align: right;"><small>Generated on Thu Oct 30 22:58:53 2008 for JamPlus manual by&nbsp;
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.7 </small></address>
</body>
View
97 docs/quick_start.dox
@@ -1,5 +1,102 @@
/*! \page quick_start Quick Start Guide
+\section quick_start_overview Overview
+JamPlus works out of the box with Visual C++. There is limited MinGW support. Other compiler suites are to come.
+
+JamPlus generates workspaces for Visual Studio 2003, 2005, and 2008. It can also generate workspaces for CodeBlocks.
+
+When the Jam executable is run, it reads a file called <tt>Jamfile.jam</tt> in the current working directory. The Jamfile contains a description of how to build the current project. In the tutorials below, we'll talk about how to properly set up a Jamfile build description.
+
+
+
+<hr>
+\section quick_start_01 Tutorial 1: Hello World!
+
+\subsection quick_start_01_setup Initial Setup
+
+For this tutorial, we are going to make a basic \b helloworld application. You will find the source code presented below in the <tt>samples/tutorials/01-helloworld/</tt> directory in the JamPlus source distribution.
+
+First, we need to create a basic <tt>main.c</tt>. It will do nothing more than print <b>Hello, world!</b> to the user.
+
+\code
+/* main.c */
+#include <stdio.h>
+
+int main()
+{
+ printf("Hello, world!\n");
+ return 0;
+}
+\endcode
+
+In the same directory as <tt>main.c</tt>, we need to create <tt>Jamfile.jam</tt> with the description of how to build the basic \b helloworld application.
+
+\code
+# This file is Jamfile.jam.
+SubDir TOP ;
+
+Application helloworld : main.c ;
+\endcode
+
+\subsection quick_start_01_setup Compiling the Tutorial
+
+Compiling the \b helloworld application is simple. Assuming the Jam executable is in your \c PATH, run the following from the <tt>01-helloworld</tt> tutorial directory:
+
+\code
+[c:\jamplus\samples\tutorials\01-helloworld]jam
+\endcode
+
+That's it. Jam will detect your Visual Studio installation automatically and build the \b helloworld application's Debug configuration. The resultant filename will be <tt>helloworld.debug.exe</tt>.
+
+Building the \b helloworld application Release configuration is performed with a command line flag. In this case, the built executable will be <tt>helloworld.release.exe</tt>.
+
+\code
+[c:\jamplus\samples\tutorials\01-helloworld]jam -sCONFIG=release
+\endcode
+
+This is all well and good if you have one of the Visual Studio compilers, but if you are running with, say, MinGW, an additional command line flag must be provided. MinGW is searched for in the <tt>c:/mingw/</tt> and <tt>d:/mingw/</tt> directories.
+
+\code
+[c:\jamplus\samples\tutorials\01-helloworld]jam -sCOMPILER=mingw
+\endcode
+
+
+
+\subsection quick_start_01_clean Cleaning Up the Tutorial Files
+
+After a build, you may notice there are a number of extra files in the directory that weren't there before. These are generally compiler intermediates, and we'll soon learn how to redirect them elsewhere.
+
+For now, instead of leaving behind various junk files, Jam can clean up after itself using the \b clean target. Targets on the Jam command line are specified \i after the command line flags. Various examples follow:
+
+\code
+rem Cleans the Debug build.
+jam clean
+
+rem Cleans the Debug build, too.
+jam -sCONFIG=debug clean
+
+rem Cleans the Release build, too.
+jam -sCONFIG=release clean
+\endcode
+
+
+
+
+\subsection quick_start_01_workspace Building a Visual Studio Workspace
+
+One of the exciting aspects of JamPlus is its ability to build Visual Studio workspaces (solutions). It does so with a set of scripts that ship in the JamPlus binary package. These scripts create an out-of-source build tree optimized for best performance within JamPlus. By being out-of-source, the source tree remains pristine.
+
+For the \b helloworld application, let's build a Visual Studio 2005 solution using the script \b JamToWorkspace.
+
+\code
+c:\jamplus\bin\scripts\JamToWorkspace --gen=vs2005 Jamfile.jam build
+\endcode
+
+In just a quick moment, the new out-of-source work area will have been created. Inside the generated <tt>01-helloworld/build/</tt> directory, you'll find a <tt>helloworld.sln</tt>. Open this file in Visual Studio to proceed.
+
+When Visual Studio has loaded the <tt>helloworld.sln</tt>, you'll find it contains the \b helloworld project within the Solution Explorer. If the \b helloworld project is not already the active project, right click on it and choose <b>Set as StartUp Project</b>.
+
+At this point, build as you normally would. Change between the Debug and Release configurations if you'd like. In fact, you can even debug as if the project were manually created!
*/
View
3  samples/helloworld/CreateVS2005Workspace.bat
@@ -1,3 +0,0 @@
-@echo off
-call %~dp0..\..\bin\scripts\JamToWorkspace.bat --gen=vs2005 Jamfile.jam ../../build/helloworld
-start ..\..\build\helloworld
View
3  samples/helloworld/CreateVS2005_MinGW_Workspace.bat
@@ -1,3 +0,0 @@
-@echo off
-call %~dp0..\..\bin\scripts\JamToWorkspace.bat --gen=vs2005 --compiler=mingw Jamfile.jam ../../build/helloworld
-start ..\..\build\helloworld
View
3  samples/tutorials/01-helloworld/CreateVS2005Workspace.bat
@@ -0,0 +1,3 @@
+@echo off
+call %~dp0..\..\..\bin\scripts\JamToWorkspace.bat --gen=vs2005 Jamfile.jam ../../../build/tutorials/01-helloworld
+start ..\..\..\build\tutorials\01-helloworld
View
3  samples/tutorials/01-helloworld/CreateVS2005_MinGW_Workspace.bat
@@ -0,0 +1,3 @@
+@echo off
+call %~dp0..\..\..\bin\scripts\JamToWorkspace.bat --gen=vs2005 --compiler=mingw Jamfile.jam ../../../build/tutorials/01-helloworld
+start ..\..\..\build\tutorials\01-helloworld
View
0  samples/helloworld/Jamfile.jam → samples/tutorials/01-helloworld/Jamfile.jam
File renamed without changes
View
0  samples/helloworld/main.c → samples/tutorials/01-helloworld/main.c
File renamed without changes
Please sign in to comment.
Something went wrong with that request. Please try again.