git.sur5r.net Git - cc65/blob - doc/make.sgml

   1 <!doctype linuxdoc system>
   2
   3 <article>
   4
   5 <title>Using GNU Make with cc65
   6 <author>Oliver Schmidt, <htmlurl url="mailto:ol.sc@web.de" name="ol.sc@web.de">
   7 <date>2009-06-26
   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 -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 ifdef CC65_TARGET
  73 define MAKEDEPEND
  74 sed -e"s!.s:!.o:!p" -e"s![^\t]*\t\(.*\)!\1:!" < $(<:.c=.u) > $(@:.o=.d)
  75 rm -f $(<:.c=.u)
  76 endef
  77 endif
  78
  79 .SUFFIXES:
  80 .PHONY: all
  81 all: $(PROGRAM)
  82
  83 ifneq ($(MAKECMDGOALS),clean)
  84 -include $(SOURCES:.c=.d)
  85 endif
  86
  87 clean:
  88         rm -f $(SOURCES:.c=.o) $(SOURCES:.c=.d) $(PROGRAM) $(PROGRAM).map
  89
  90 %.o: %.c
  91         $(CC) -c $(CFLAGS) $< -o $@
  92         @$(MAKEDEPEND)
  93
  94 $(PROGRAM): $(SOURCES:.c=.o)
  95         $(CC) $(LDFLAGS) $^ -o $@
  96 </verb></tscreen>
  97
  98 <bf/Important:/ When using the sample Makefile above via copy & paste it is
  99 necessary to replace the eight spaces at the beginning of command lines (lines
 100 33, 36, 37 and 40) with a tab character (ASCII code 9).
 101
 102
 103 <sect1>Invoking the sample Makefile<p>
 104
 105 Without any specific configuration the sample Makefile will compile and link
 106 using GCC. In order to rather use cc65 the variable <tt/CC65_TARGET/ needs to be
 107 defined. This may by done as an environment variable or simply as part of the
 108 Makefile. However to quickly switch between compilers and/or cc65 targets it is
 109 best done on the GNU Make command line like this:
 110
 111 <tscreen><verb>
 112 make CC65_TARGET=c64
 113 </verb></tscreen>
 114
 115 The sample Makefile doesn't require cc65 to be "installed" in any way. Rather it
 116 only presumes the single variable <tt/CC65_HOME/ to point to the directory the
 117 cc65 packages were unpacked into. Again there are several ways to define this
 118 variable but as its value typically won't change often it is best done as an
 119 environment variable.
 120
 121
 122 <sect1>Understanding the sample Makefile<p>
 123
 124 Most parts of the sample Makefile follow the guidelines in the
 125 <htmlurl url="http://www.gnu.org/software/make/manual/make.html" name="GNU Make Manual">
 126 that can be searched online for background information. The automatic generation of
 127 dependency however rather works as described by the GNU Make maintainer Paul D. Smith in
 128 <htmlurl url="http://make.paulandlesley.org/autodep.html#advanced" name="Advanced Auto-Dependencies">.
 129
 130 In the meantime GCC supports this method directly with the preprocessor option
 131 <tt/-MP/ while cc65 requires some post-processing of the dependency file with
 132 <tt/sed/ adding a second line like in this example:
 133
 134 <tscreen><verb>
 135 foo.o:  foo.c foo.h bar.h
 136 foo.c foo.h bar.h:
 137 </verb></tscreen>
 138
 139
 140 <sect1>Invoking the sample Makefile on Windows<p>
 141
 142 The recommended way to use GNU Make on Windows is to install it as part of a
 143 Cygwin environment. For more information see the Cygwin home page:
 144
 145 <url url="http://www.cygwin.com/">
 146
 147 If however installing Cygwin shouldn't be an option for one or the other reason
 148 then the sample Makefile may be invoked from the Windows Command Prompt (cmd.exe)
 149 by downloading the following programs:
 150
 151 <itemize>
 152 <item>make.exe: <url url="http://gnuwin32.sourceforge.net/packages/make.htm">
 153 <item>sed.exe: <url url="http://gnuwin32.sourceforge.net/packages/sed.htm">
 154 <item>rm.exe: <url url="http://gnuwin32.sourceforge.net/packages/coreutils.htm">
 155 </itemize>
 156
 157
 158
 159 <sect>Target-specific Variable Values<p>
 160
 161 The very limited resources of the cc65 target machines now and then require
 162 manual optimization of the build process by compiling individual source files
 163 with different compiler options. GNU Make offers
 164 <htmlurl url="http://www.gnu.org/software/make/manual/html_node/Target_002dspecific.html" name="Target-specific Variable Values">
 165 perfectly suited for doing so. For example placing the code of the two modules
 166 <tt/foo/ and <tt/bar/ in the segment <tt/FOOBAR/ can be archived with this
 167 target-specific variable definition:
 168
 169 <tscreen><verb>
 170 foo.o bar.o: CFLAGS += --code-name FOOBAR
 171 </verb></tscreen>
 172
 173 </article>