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

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