-
Notifications
You must be signed in to change notification settings - Fork 43
/
quick_start.dox
167 lines (100 loc) · 6.38 KB
/
quick_start.dox
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
/*! \page quick_start Quick Start Guide
\section quick_start_overview Overview
JamPlus works out of the box with C/C++ compilation for Visual C++ compilers, GCC, MinGW, and others. It can also generate workspaces for Visual Studio 20xx, Visual C++ 6, Xcode, and 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_00 Tutorial 0: Use Jam to Build Simple Applications
\subsection quick_start_00_simple_helloworld Building helloworld
For this tutorial, we are going to make a basic \b helloworld application.
First, we need to create a <tt>helloworld.c</tt> file. It will do nothing more than print <b>Hello, world!</b> to the user.
\code
/* helloworld.c */
#include <stdio.h>
int main()
{
printf("Hello, world!\n");
return 0;
}
\endcode
Straight out of the box, you can run <tt>jam</tt> within the directory of <tt>helloworld.c</tt>, and Jam will build a <tt>helloworld</tt> executable using all of the <tt>*.c</tt>, <tt>*.cpp</tt>, <tt>*.m</tt>, and <tt>*.mm</tt> files in the directory.
\code
# helloworld.exe (or the equivalent) is generated. It might not be named helloworld.exe, because
# the first source file title in the directory is used as the executable name.
jam
# Remove the executable and all intermediate files.
jam clean
# helloworld.exe (or the equivalent) is generated. It might not be named helloworld.exe, because
# the first source file title in the directory is used as the executable name. To override this,
# add helloworld to the command-line:
jam helloworld
# Remove the helloworld executable and all intermediate files.
jam clean:helloworld
\endcode
While this is a convenient Jam feature, generally a more complex build is needed. We'll make one of those in \ref quick_start_01.
<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.
First, we need to create a <tt>helloworld.c</tt> file. It will do nothing more than print <b>Hello, world!</b> to the user.
\code
/* helloworld.c */
#include <stdio.h>
int main()
{
printf("Hello, world!\n");
return 0;
}
\endcode
In the same directory as <tt>helloworld.c</tt>, we also 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.
#
# Please note that Jam tokens are whitespace separated. Even the semicolon
# delineating the end of statements has whitespace before it.
C.Application helloworld : helloworld.c ;
\endcode
\subsection quick_start_01_compiling Compiling the Tutorial
Compiling the \b helloworld application is simple. Assuming the Jam executable is in your \c PATH, run the following from the directory containing your <tt>Jamfile.jam</tt> and <tt>main.c</tt>:
\code
jam
\endcode
That's it. Jam will detect your OS and then the appropriate compilers for your platform. On Windows, Jam looks for Visual Studio 2015, then 2013, 2012, 2010, 2008, and so on until Visual C++ 6. If it can't find any of those, it looks for a MinGW installation in the <tt>c:/Program Files/mingw-x64/</tt> and <tt>c:/mingw/</tt> directories. On Mac OS X, Jam looks for clang or gcc. When a compiler is found, the \b helloworld application's Release configuration is built. The resultant filename will be <tt>.build/win64-release/TOP/helloworld/helloworld.exe</tt> on Windows and in a similar location but with an executable name of <tt>helloworld</tt> on other platforms.
Building the \b helloworld application Debug configuration is performed with a command line flag. In this case, the built executable will be <tt>.build/win64-debug/TOP/helloworld/helloworld.exe</tt> on Windows and in a similar location but with an executable name removing the <tt>.exe</tt> on other platforms.
\code
jam CONFIG=debug
\endcode
or, preferred:
\code
jam C.TOOLCHAIN=-/debug
\endcode
If you would like to run with another compiler by default, such as MinGW, an additional command line flag must be provided.
\code
jam COMPILER=mingw
\endcode
\subsection quick_start_01_clean Cleaning Up the Tutorial Files
Compiler intermediates and outputs are, by default, stored within a <tt>.build/</tt> directory. These files can be cleaned up using the \c clean target.
\code
rem Cleans the default platform's Release build.
jam clean
rem Cleans the default platform's Release build, too.
jam CONFIG=release clean
rem Cleans the Debug build.
jam CONFIG=debug clean
rem Cleans the Debug build.
jam C.TOOLCHAIN=-/debug clean
\endcode
\subsection quick_start_01_workspace Building an IDE Workspace
One of the exciting features of JamPlus is its ability to build IDE workspaces for Visual Studio or Xcode or others. It does so with a set of scripts that are present in the JamPlus <tt>bin/</tt> directory. 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, and all compiler intermediates are stored in a separate location.
For the \b helloworld application, let's build a Visual Studio 2015 solution on Windows or an Xcode workspace on macOS.
\code
jam --workspace
\endcode
It may be preferable to output to a different directory than <tt>.build/</tt>.
\code
jam --workspace --gen=vs2015 Jamfile.jam build
\endcode
After running <tt>jam --workspace</tt>, the new out-of-source work area will have been created. Inside the generated <tt>build/_workspaces_/IDE/</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>.
On Mac OS X, you'll find the appropriate .xcodeproj as <tt>build/_workspaces_/xcode/helloworld.xcworkspace</tt>. Open this project file in Xcode, and choose the appropriate scheme (such as <tt>helloworld-release</tt>).
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!
*/