]> git.sur5r.net Git - cc65/blob - doc/using-make.sgml
Merge pull request #7 from cc65/master
[cc65] / doc / using-make.sgml
1 <!doctype linuxdoc system>
2
3 <article>
4
5 <title>Using GNU Make with cc65
6 <author><url url="mailto:ol.sc@web.de" name="Oliver Schmidt">
7 <date>2014-04-12
8
9 <abstract>
10 How to build your program using the GNU Make utility.
11 </abstract>
12
13 <!-- Table of contents -->
14 <toc>
15
16 <!-- Begin the document -->
17
18 <sect>Overview<p>
19
20 This document describes how to build your programs using the cc65 development
21 tools and the GNU Make utility.
22
23 The cc65 development package doesn't come with a make utility. However this is
24 no issue because GNU Make works very nicely with cc65.
25
26
27
28 <sect>What is GNU Make?<p>
29
30 GNU Make is a both very powerful and very popular make utility. It might even
31 be called the de facto standard for make utilities. For more information see
32 the GNU Make home page:
33
34 <url url="http://www.gnu.org/software/make/">
35
36 The cc65 development package is available as binaries for several host systems
37 and can easily built for quite some additional systems. The very same is true
38 for GNU Make so a cc65-based project coming with a GNU Make Makefile can easily
39 be built by any cc65 developer no matter what host system is used.
40
41 Because of the strong alignment of the cc65 compiler with the ISO C standard it
42 is very well feasible to compile a single C code base both with the cc65
43 compiler and other C compilers like for example GCC. GNU Make turns out to be
44 very well suited to build projects for several target systems using multiple
45 compilers as it isn't tied to any C compiler.
46
47
48
49 <sect>A sample Makefile<p>
50
51 This Makefile is a fully functional sample for compiling several C sources
52 (here <tt/foo.c/ and <tt/bar.c/) and link the resulting object files into an
53 executable program (here <tt/foobar/):
54
55 <tscreen><verb>
56 SOURCES = foo.c bar.c
57
58 PROGRAM = foobar
59
60 ifdef CC65_TARGET
61 CC      = $(CC65_HOME)/bin/cl65
62 CFLAGS  = -t $(CC65_TARGET) --create-dep $(<:.c=.d) -O
63 LDFLAGS = -t $(CC65_TARGET) -m $(PROGRAM).map
64 else
65 CC      = gcc
66 CFLAGS  = -MMD -MP -O
67 LDFLAGS = -Wl,-Map,$(PROGRAM).map
68 endif
69
70 ########################################
71
72 .SUFFIXES:
73 .PHONY: all clean
74 all: $(PROGRAM)
75
76 ifneq ($(MAKECMDGOALS),clean)
77 -include $(SOURCES:.c=.d)
78 endif
79
80 %.o: %.c
81         $(CC) -c $(CFLAGS) -o $@ $<
82
83 $(PROGRAM): $(SOURCES:.c=.o)
84         $(CC) $(LDFLAGS) -o $@ $^
85
86 clean:
87         $(RM) $(SOURCES:.c=.o) $(SOURCES:.c=.d) $(PROGRAM) $(PROGRAM).map
88 </verb></tscreen>
89
90 <bf/Important:/ When using the sample Makefile above via copy & paste it is
91 necessary to replace the eight spaces at the beginning of command lines (lines
92 26, 29 and 32) with a tab character (ASCII code 9).
93
94
95 <sect1>Invoking the sample Makefile<p>
96
97 Without any specific configuration the sample Makefile will compile and link
98 using GCC. In order to rather use cc65 the variable <tt/CC65_TARGET/ needs to be
99 defined. This may by done as an environment variable or simply as part of the
100 Makefile. However to quickly switch between compilers and/or cc65 targets it is
101 best done on the GNU Make command line like this:
102
103 <tscreen><verb>
104 make CC65_TARGET=c64
105 </verb></tscreen>
106
107 The sample Makefile presumes the variable <tt/CC65_HOME/ to point to the
108 directory cc65 is located in. Again there are several ways to define this
109 variable but as its value typically won't change often it is best done as an
110 environment variable. On Windows the cc65 .exe installer package takes care
111 of creating a <tt/CC65_HOME/ environment variable.
112
113
114 <sect1>Understanding the sample Makefile<p>
115
116 Most parts of the sample Makefile follow the guidelines in the
117 <url url="http://www.gnu.org/software/make/manual/make.html" name="GNU Make Manual">
118 that can be searched online for background information. The automatic generation of
119 dependency however rather works as described by the GNU Make maintainer Paul D. Smith in
120 <url url="http://make.paulandlesley.org/autodep.html#advanced" name="&dquot;Advanced Auto-Dependencies&dquot;">.
121 Fortunately both GCC and cc65 directly support this method in the meantime.
122
123
124 <sect1>Invoking the sample Makefile on Windows<p>
125
126 The recommended way to use GNU Make on Windows is to install it as part of a
127 Cygwin environment. For more information see the Cygwin home page:
128
129 <url url="http://www.cygwin.com/">
130   
131 If however installing Cygwin shouldn't be an option for one or the other reason
132 then the sample Makefile may be invoked from the Windows Command Prompt (cmd.exe)
133 by downloading the following programs:
134
135 <itemize>
136 <item><url name="make.exe" url="http://gnuwin32.sourceforge.net/packages/make.htm">
137 <item><url name="rm.exe" url="http://gnuwin32.sourceforge.net/packages/coreutils.htm">
138 </itemize>
139
140
141
142 <sect>Target-specific Variable Values<p>
143   
144 The very limited resources of the cc65 target machines now and then require
145 manual optimization of the build process by compiling individual source files
146 with different compiler options. GNU Make offers
147 <url url="http://www.gnu.org/software/make/manual/html_node/Target_002dspecific.html" name="Target-specific Variable Values">
148 perfectly suited for doing so. For example placing the code of the two modules 
149 <tt/foo/ and <tt/bar/ in the segment <tt/FOOBAR/ can be achieved with this
150 target-specific variable definition:
151
152 <tscreen><verb>
153 foo.o bar.o: CFLAGS += --code-name FOOBAR
154 </verb></tscreen>
155   
156 </article>