Blame - docs/GettingStarted.html - platform/external/llvm

Guochun Shi

f4688a8

2002-07-17 23:05:56 +0000

[diff] [blame]

1

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

2

<html>

John Criswell

8df90e0

2003-06-11 20:46:40 +0000

[diff] [blame^]

3

<head>

4

<title>Getting Started with LLVM System</title>

</head>

<h1>Getting Started with the LLVM System<br>

10

<font size="3">By: <a href="mailto:gshi1@uiuc.edu">Guochun Shi</a>, <a

11

href="mailto:sabre@nondot.org">Chris Lattner</a> and <a

12

href="http://www.cs.uiuc.edu/%7Evadve">Vikram Adve</a> </font></h1>

13

</center>

14

15

16

<h2><a name="Contents">Contents</a></h2>

17

18

19

<ul>

20

<li><a href="#overview">Overview</a> </li>

21

<li><a href="#starting">Getting started with LLVM</a>

Chris Lattner

96768ea

2003-02-14 04:22:13 +0000

[diff] [blame]

22

<ol>

John Criswell

8df90e0

2003-06-11 20:46:40 +0000

[diff] [blame^]

23

<li><a href="#quickstart">Getting started quickly (a summary)</a>

24

</li>

25

<li><a href="#checkout">Checkout LLVM from CVS</a> </li>

26

<li><a href="#terminology">Terminology and Notation</a> </li>

27

<li><a href="#objfiles">The location for object files</a> </li>

28

<li><a href="#config">Local Configuration Options</a> </li>

29

<li><a href="#environment">Setting up your environment</a>

30

</li>

31

<li><a href="#compile">Compiling the source code</a> </li>

Chris Lattner

96768ea

2003-02-14 04:22:13 +0000

[diff] [blame]

32

</ol>

John Criswell

8df90e0

2003-06-11 20:46:40 +0000

[diff] [blame^]

33

</li>

34

<li><a href="#layout">Program layout</a>

35

<ol>

36

<li><a href="#cvsdir">CVS directories</a> </li>

37

<li><a href="#dd"><tt>Depend</tt>, <tt>Debug</tt>, &

38

<tt>Release</tt> directories</a></li>

39

<li><a href="#include"><tt>llvm/include</tt></a> </li>

40

41

42

<li><a href="#tools"><tt>llvm/tools</tt></a> </li>

43

</ol>

44

</li>

45

<li><a href="#tutorial">An example using the LLVM tool chain</a>

46

</li>

47

<li><a href="#links">Links</a> </li>

48

</ul>

49

50

51

52

<h2><a name="overview"><b>Overview</b></a></h2>

53

</center>

54

55

56

<p>The <a href="" starting="">next section</a> of this guide is meant to

57

get you up and running with LLVM, and to give you some basic information

58

about the LLVM environment. The <a href="" #quickstart="">first subsection</a>

59

gives a short summary for those who are already familiar with the system

60

and want to get started as quickly as possible. </p>

61

<p>The later sections of this guide describe the <a href="" #layout="">general

62

layout</a> of the LLVM source-tree, a <a href="#tutorial">simple example</a>

63

using the LLVM tool chain, and <a href="#links">links</a> to find more information

64

about LLVM or to get help via e-mail.

65

</p>

66

67

<h2><a name="starting"><b>Getting Started</b></a></h2>

68

</center>

69

70

71

72

<h3><a name="quickstart"><b>Getting Started Quickly (A Summary)</b></a></h3>

73

74

Here's the short story for getting up and running quickly with LLVM:

75

76

<ol>

77

<li>Find the path to the CVS repository containing LLVM (we'll call

78

this <i>CVSROOTDIR</i>). </li>

79

<li><tt>cd <i>where-you-want-llvm-to-live</i></tt> </li>

80

<li><tt>cvs -d <i>CVSROOTDIR</i> checkout llvm</tt> </li>

81

82

<li>Edit <tt>Makefile.config</tt> to set local paths. This includes

83

setting the install location of the C frontend and the various paths

84

to the C and C++ compilers used to build LLVM itself. </li>

85

<li>Set your LLVM_LIB_SEARCH_PATH environment variable. </li>

86

<li><tt>gmake -k |& tee gnumake.out    # this is

87

csh or tcsh syntax</tt> </li>

88

</ol>

89

90

<p>See <a href="#environment">Setting up your environment</a> on tips to

91

simplify working with the LLVM front-end and compiled tools. See the

92

other sub-sections below for other useful details in working with LLVM,

93

or go straight to <a href="#layout">Program Layout</a> to learn about

94

the layout of the source code tree.

95

</p>

96

<h3><a name="terminology">Terminology and Notation</a></h3>

97

98

99

<p>Through this manual, the following names are used to denote paths

100

specific to the local system and working environment. <i>These are not

101

environment variables you need to set, but just strings used in the rest

102

of this document below</i>. In any of the examples below, simply replace

103

each of these names with the appropriate pathname on your local system.

Chris Lattner

1db872d

2002-09-06 16:26:13 +0000

[diff] [blame]

104

All these paths are absolute:</p>

John Criswell

8df90e0

2003-06-11 20:46:40 +0000

[diff] [blame^]

<ul>

</ul>

110

111

<h3><a name="checkout">Checkout LLVM from CVS</a></h3>

112

113

114

<p>Before checking out the source code, you will need to know the path to

115

the CVS repository containing LLVM source code (we'll call this <i>CVSROOTDIR</i>

116

below). Ask the person responsible for your local LLVM installation

117

to give you this path. </p>

118

<p>To get a fresh copy of the entire source code, all you need to do

119

is check it out from CVS as follows: </p>

120

<ul>

121

<li><tt>cd <i>where-you-want-llvm-to-live</i></tt> </li>

122

<li><tt>cvs -d <i>CVSROOTDIR</i> checkout llvm</tt>

<p></p>

</li>

</ul>

<p>This will create an '<tt>llvm</tt>' directory in the current directory

128

and fully populate it with the LLVM source code, Makefiles, test directories,

129

and local copies of documentation files.</p>

130

131

132

<h3><a name="config">Local Configuration Options</a></h3>

133

134

135

<p>The file <tt>llvm/Makefile.config</tt> defines the following path

136

variables which are specific to a particular installation of LLVM.

137

These should need to be modified only once after checking out a copy

138

of LLVM (if the default values do not already match your system):

</p>

<ul>

<p></p>

<li><i>CXX</i> = Path to C++ compiler to use.

144

<p></p>

145

</li>

146

<li><i>OBJ_ROOT</i> = Path to the llvm directory where object files

147

should be placed. (See the Section on <a href="#objfiles"> The

148

location for LLVM object files</a> for more information.)

149

<p></p>

150

</li>

151

<li><i>LLVMGCCDIR</i> = Path to the location of the LLVM front-end

152

binaries and associated libraries.

153

<p></p>

154

</li>

155

<li><i>PURIFY</i> = Path to the purify program. </li>

156

</ul>

157

In addition to settings in this file, you must set a <tt>LLVM_LIB_SEARCH_PATH</tt>

158

environment variable in your startup scripts. This environment variable

159

is used to locate "system" libraries like "<tt>-lc</tt>" and "<tt>-lm</tt>"

160

when linking. This variable should be set to the absolute path for the

161

bytecode-libs subdirectory of the C front-end install. For example,

162

<tt>/home/vadve/lattner/local/x86/llvm-gcc/bytecode-libs</tt> is used

163

for the X86 version of the C front-end on our research machines.

164

165

</p>

166

<h3><a name="objfiles">The location for LLVM object files</a></h3>

167

168

169

<p>The LLVM make system sends most output files generated during the build

170

into the directory defined by the variable OBJ_ROOT in <tt>llvm/Makefile.config</tt>.

171

This can be either just your normal LLVM source tree or some other directory

172

writable by you. You may wish to put object files on a different filesystem

173

either to keep them from being backed up or to speed up local builds.

174

</p>

175

<p>If you do not wish to use a different location for object files (i.e.

176

building into the source tree directly), just set this variable to ".".</p>

177

178

</p>

179

<h3><a name="environment">Setting up your environment</a></h3>

180

181

<i>NOTE: This step is optional but will set up your environment so you

182

can use the compiled LLVM tools with as little hassle as possible.</i>)

183

184

<p>Add the following lines to your <tt>.cshrc</tt> (or the corresponding

185

lines to your <tt>.profile</tt> if you use a bourne shell derivative).

186

</p>

187

<pre> # Make the C front end easy to use...<br> alias llvmgcc <i>LLVMGCCDIR</i><tt>/bin/llvm-gcc</tt>

Chris Lattner

7fe7f81

2002-07-24 19:51:14 +0000

[diff] [blame]

188

189

# Make the LLVM tools easy to use...

John Criswell

8df90e0

2003-06-11 20:46:40 +0000

[diff] [blame^]

190

setenv PATH <i>OBJ_ROOT</i>/llvm/tools/Debug:${PATH}<br> </pre>

191

The <tt>llvmgcc</tt> alias is useful because the C compiler is not

192

included in the CVS tree you just checked out.

193

<p>The other <a href="#tools">LLVM tools</a> are part of the LLVM source

194

base and are built when compiling LLVM. They will be built into the

195

<tt><i>OBJ_ROOT</i>/tools/Debug</tt> directory.</p>

196

Chris Lattner

1db872d

2002-09-06 16:26:13 +0000

[diff] [blame]

197

John Criswell

8df90e0

2003-06-11 20:46:40 +0000

[diff] [blame^]

198

<h3><a name="compile">Compiling the source code</a></h3>

199

200

201

<p>Every directory in the LLVM source tree includes a <tt>Makefile</tt> to

202

build it and any subdirectories that it contains. These makefiles require

203

GNU Make (<tt>gmake)</tt> instead of <tt>make</tt> to build them, but

204

can otherwise be used freely. To build the entire LLVM system, just

205

enter the top level <tt>llvm</tt> directory and type <tt>gmake</tt>.

206

A few minutes later you will hopefully have a freshly compiled toolchain

207

waiting for you in <tt><i>OBJ_ROOT</i></tt><tt>/llvm/tools/Debug</tt>.

208

If you want to look at the libraries that were compiled, look in <tt><i>OBJ_ROOT</i></tt><tt>/llvm/lib/Debug</tt>.</p>

209

If you get an error about the <tt>/localhome</tt> directory, chances

210

are good that something has been misconfigured.  Follow the instructions

211

in the section about <a href="#environment">Setting Up Your Environment.</a>

212

213

214

215

<h2><a name="layout"><b>Program Layout</b></a></h2>

216

</center>

217

218

219

<p>One useful source of infomation about the LLVM sourcebase is the LLVM

220

<a href="http://www.doxygen.org">doxygen</a> documentation, available at

221

<tt><a href="http://llvm.cs.uiuc.edu/doxygen/">http://llvm.cs.uiuc.edu/doxygen/</a></tt>.

222

The following is a brief introduction to code layout:</p>

223

224

225

<h3><a name="cvsdir"><tt>CVS</tt> directories</a></h3>

226

227

Every directory checked out of CVS will contain a <tt>CVS</tt> directory;

228

for the most part, these can just be ignored.

229

230

<h3><a name="ddr"><tt>Depend</tt>, <tt>Debug</tt>, & <tt>Release</tt>

Chris Lattner

44ac659

2002-08-09 16:14:56 +0000

[diff] [blame]

231

directories</a></h3>

John Criswell

8df90e0

2003-06-11 20:46:40 +0000

[diff] [blame^]

232

233

If you are building with the "<tt>OBJ_ROOT=.</tt>" option enabled in

234

the <tt>Makefile.config</tt> file, most source directories will contain

235

two directories, <tt>Depend</tt> and <tt>Debug</tt>. The <tt>Depend</tt>

236

directory contains automatically generated dependance files which are

237

used during compilation to make sure that source files get rebuilt if

238

a header file they use is modified. The <tt>Debug</tt> directory holds

239

the object files, library files, and executables that are used for building

240

a debug enabled build. The <tt>Release</tt> directory is created to

241

hold the same files when the <tt>ENABLE_OPTIMIZED=1</tt> flag is passed

242

to <tt>gmake</tt>, causing an optimized built to be performed.

243

244

</p>

245

<h3><a name="include"><tt>llvm/include</tt></a></h3>

246

247

This directory contains public header files exported from the LLVM

248

library. The two main subdirectories of this directory are:

249

250

<ol>

251

<li><tt>llvm/include/llvm</tt> - This directory contains all of the

252

LLVM specific header files. This directory also has subdirectories

253

for different portions of LLVM: <tt>Analysis</tt>, <tt>CodeGen</tt>,

254

<tt>Reoptimizer</tt>, <tt>Target</tt>, <tt>Transforms</tt>, etc...

255

</li>

256

<li><tt>llvm/include/Support</tt> - This directory contains generic

257

support libraries that are independant of LLVM, but are used by LLVM.

258

For example, some C++ STL utilities and a Command Line option processing

259

library. </li>

260

</ol>

261

262

263

264

265

This directory contains most source files of LLVM system. In LLVM almost

266

all code exists in libraries, making it very easy to share code among

267

the different <a href="#tools">tools</a>.

268

269

270

<dt><tt>llvm/lib/VMCore/</tt></dt>

271

<dd> This directory holds the core LLVM source files that implement

272

core classes like Instruction and BasicBlock. </dd>

273

<dt><tt>llvm/lib/AsmParser/</tt></dt>

274

<dd> This directory holds the source code for the LLVM assembly language

275

parser library. </dd>

276

<dt><tt>llvm/lib/ByteCode/</tt></dt>

277

<dd> This directory holds code for reading and write LLVM bytecode.

278

</dd>

279

<dt><tt>llvm/lib/CWriter/</tt></dt>

280

<dd> This directory implements the LLVM to C converter. </dd>

281

<dt><tt>llvm/lib/Analysis/</tt></dt>

282

<dd> This directory contains a variety of different program analyses,

283

such as Dominator Information, Call Graphs, Induction Variables, Interval

284

Identification, Natural Loop Identification, etc... </dd>

285

<dt><tt>llvm/lib/Transforms/</tt></dt>

286

<dd> This directory contains the source code for the LLVM to LLVM

287

program transformations, such as Aggressive Dead Code Elimination,

288

Sparse Conditional Constant Propagation, Inlining, Loop Invarient Code

289

Motion, Dead Global Elimination, Pool Allocation, and many others...

290

</dd>

291

<dt><tt>llvm/lib/Target/</tt></dt>

292

<dd> This directory contains files that describe various target architectures

293

for code generation. For example, the llvm/lib/Target/Sparc directory

294

holds the Sparc machine description.<br>

295

</dd>

296

<dt><tt>llvm/lib/CodeGen/</tt></dt>

297

<dd> This directory contains the major parts of the code generator:

298

Instruction Selector, Instruction Scheduling, and Register Allocation.

299

</dd>

300

<dt><tt>llvm/lib/Reoptimizer/</tt></dt>

301

<dd> This directory holds code related to the runtime reoptimizer

302

framework that is currently under development. </dd>

303

<dt><tt>llvm/lib/Support/</tt></dt>

304

<dd> This directory contains the source code that corresponds to

305

the header files located in <tt>llvm/include/Support/</tt>. </dd>

306

</dl>

307

308

309

310

311

312

<p>This directory contains regression tests and source code that is used

313

to test the LLVM infrastructure...</p>

314

315

316

<h3><a name="tools"><tt>llvm/tools</tt></a></h3>

317

318

319

<p>The <b>tools</b> directory contains the executables built out of the

320

libraries above, which form the main part of the user interface. You

321

can always get help for a tool by typing <tt>tool_name --help</tt>.

322

The following is a brief introduction to the most important tools.</p>

Chris Lattner

7fe7f81

2002-07-24 19:51:14 +0000

[diff] [blame]

323

John Criswell

8df90e0

2003-06-11 20:46:40 +0000

[diff] [blame^]

324

325

326

<dd>The assembler transforms the human readable LLVM assembly to

LLVM bytecode.

</dd>

<dd>The disassembler transforms the LLVM bytecode to human readable

332

LLVM assembly. Additionally it can convert LLVM bytecode to C, which

333

is enabled with the <tt>-c</tt> option.

</dd>

<dd> <tt>lli</tt> is the LLVM interpreter, which can directly execute

338

LLVM bytecode (although very slowly...). In addition to a simple intepreter,

339

<tt>lli</tt> is also has debugger and tracing modes (entered by

340

specifying <tt>-debug</tt> or <tt>-trace</tt> on the command line,

respectively).

</dd>

<dd> <tt>llc</tt> is the LLVM backend compiler, which translates

346

LLVM bytecode to a SPARC assembly file.

347

348

</dd>

349

<dt><tt><b>llvmgcc</b></tt></dt>

350

<dd> <tt>llvmgcc</tt> is a GCC based C frontend that has been retargeted

351

to emit LLVM code as the machine code output. It works just like any

352

other GCC compiler, taking the typical <tt>-c, -S, -E, -o</tt> options

353

that are typically used. The source code for the <tt>llvmgcc</tt>

354

tool is currently not included in the LLVM cvs tree because it is quite

355

large and not very interesting.

356

357

<ol>

358

<dt><tt><b>gccas</b></tt></dt>

359

<dd> This tool is invoked by the <tt>llvmgcc</tt> frontend

360

as the "assembler" part of the compiler. This tool actually assembles

361

LLVM assembly to LLVM bytecode, performs a variety of optimizations,

362

and outputs LLVM bytecode. Thus when you invoke <tt>llvmgcc -c x.c

363

-o x.o</tt>, you are causing <tt>gccas</tt> to be run, which writes

364

the <tt>x.o</tt> file (which is an LLVM bytecode file that can be

365

disassembled or manipulated just like any other bytecode file).

366

The command line interface to <tt>gccas</tt> is designed to be as

367

close as possible to the <b>system</b> '<tt>as</tt>' utility so that

368

the gcc frontend itself did not have to be modified to interface

369

to a "wierd" assembler.

370

371

</dd>

372

<dt><tt><b>gccld</b></tt></dt>

373

<dd> <tt>gccld</tt> links together several LLVM bytecode files

374

into one bytecode file and does some optimization. It is the linker

375

invoked by the gcc frontend when multiple .o files need to be linked

376

together. Like <tt>gccas</tt> the command line interface of <tt>gccld</tt>

377

is designed to match the system linker, to aid interfacing with the

378

GCC frontend.

379

380

</dd>

Chris Lattner

7fe7f81

2002-07-24 19:51:14 +0000

[diff] [blame]

381

</ol>

John Criswell

8df90e0

2003-06-11 20:46:40 +0000

[diff] [blame^]

382

</dd>

383

384

<dd> <tt>opt</tt> reads LLVM bytecode, applies a series of LLVM to

385

LLVM transformations (which are specified on the command line), and

386

then outputs the resultant bytecode. The '<tt>opt --help</tt>' command

387

is a good way to get a list of the program transformations available

in LLVM.

</dd>

<dt><tt><b>analyze</b></tt></dt>

392

<dd> <tt>analyze</tt> is used to run a specific analysis on an input

393

LLVM bytecode file and print out the results. It is primarily useful

394

for debugging analyses, or familiarizing yourself with what an analysis

does.

</dd>

</dl>

400

401

<h2><a name="tutorial">An example using the LLVM tool chain</a></h2>

</a>

<ol>

<a name="tutorial"> <li>First, create a simple C file, name it 'hello.c':

406

407

<pre> #include <stdio.h><br> int main() {<br> printf("hello world\n");<br> return 0;<br> }<br> </pre>

408

</li>

409

<li>Next, compile the C file into a LLVM bytecode file:

410

<p> <tt>% llvmgcc hello.c -o hello</tt></p>

411

<p> This will create two result files: <tt>hello</tt> and

412

<tt>hello.bc</tt>. The <tt>hello.bc</tt> is the LLVM bytecode that

413

corresponds the the compiled program and the library facilities that it

414

required. <tt>hello</tt> is a simple shell script that runs the bytecode

415

file with <tt>lli</tt>, making the result directly executable.</p>

416

417

</li>

418

<li>Run the program. To make sure the program ran, execute one of the

419

following commands:

420

<p> <tt>% ./hello</tt></p>

421

422

<p> <tt>% lli hello.bc</tt></p>

423

424

</li>

425

<li>Use the <tt>dis</tt> utility to take a look at the LLVM assembly

code:

</li>

<li>Compile the program to native Sparc assembly using the code generator:

431

<p> <tt>% llc hello.bc -o hello.s</tt></p>

432

433

</li>

434

<li>Assemble the native sparc assemble file into a program:

435

<p> <tt>% /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.sparc</tt></p>

436

437

</li>

438

<li>Execute the native sparc program:

439

<p> <tt>% ./hello.sparc</tt></p>

</li>

</a>

</ol>

</a>

<h2><a name="links">Links</a></h2>

447

448

449

<p>This document is just an <b>introduction</b> to how to use LLVM to do

450

some simple things... there are many more interesting and complicated

451

things that you can do that aren't documented here (but we'll gladly

452

accept a patch if you want to write something up!). For more information

453

about LLVM, check out:</p>

454

455

<ul>

456

<li><a href="http://llvm.cs.uiuc.edu/">LLVM homepage</a></li>

457

<li><a href="http://llvm.cs.uiuc.edu/doxygen/">LLVM doxygen tree</a></li>

</ul>

<hr> If you have any questions or run into any snags (or you have any

462

additions...), please send an email to <a

463

href="mailto:sabre@nondot.org">Chris Lattner</a>.

464

<p></p>

465

466

Last modified: Tue Jun 3 22:06:43 CDT 2003  <br>

467

</body>

Guochun Shi

f4688a8

2002-07-17 23:05:56 +0000

[diff] [blame]

468

</html>