# Mfile help

# Simple Makefile generator for AVR-GCC

Copyright © 2003, 2004 Jörg Wunsch

This simple Makefile generator is meant as an aid to quickly customize the WinAVR Makefile template, producing a file called `Makefile` in the current directory as result.

The application consists of a (scrollable) text editor widget, and a menu bar.

The File menu has only two entries:

- Save writes the contents of the text editor widget to a file called `Makefile`. Should any file by that name already exist, it will be renamed. Under Unix, a tilde will be appended to the old name, all other platforms append a `.bak` suffix.
- Save As opens a filename selection dialog, and allows the user to select a file to save to. After selecting the file name, it behaves identical to Save.
- Open opens a filename selection dialog, requesting an existing file to be opened by the user. This file will be loaded into the editor buffer, and the Makefile menu will be updated accordingly.
- Exit will quit the application. No checks whatsoever are done to ensure the user has saved his editing work before.

The Makefile menu allows customization of the generated Makefile. Note that the various menu items described below will only be present if the corresponding feature is present in the parsed template or input file. This menu is divided into three areas:

- Code generation options
  - The entry Main file name opens a popup window that asks for the basic name of this project. This will become the base name for all major output files (ELF file, MCU output file, several auxiliary files). By default, it will also serve as the name of the primary C source file, with a `.c` suffix appended. The popup will be closed by pressing <Enter> in the entry field.
  - The entries MCU type, Output format, Optimization level, and C standard level select possible values out of a predefined list. When selecting one of these options, the respective Makefile macro will be modified accordingly, and the widget will be adjusted so the new values can be seen immediately.
  - The entry printf() options works similar, only it does not modify a Makefile macro of its own but edits the PRINTF_LIB macro instead. Note that setting this away from none/standard will cause the generated application to always include the code for vfprintf() (which is huge), regardless of whether the application actually uses any member of the printf() family. See the avr-libc documentation for the meaning of the different options.
  - Likewise, changing the scanf() options changes the macro SCANF_LIB, in the same manner. Note that the `scanf()` format %[ (string match out of a set of characters) will only be present in the floating point version since it requires a lot of code, as well as using `malloc()` (which is otherwise only required for the floating point version).
  - The entry C/C++ source file(s) opens a popup that asks for a list of C (or C++) source files. C source files get the suffix `.c` (lower-case letter c), C++ source files get either of `.C` (capital c), `.cxx`, or `.cc`. Multiple file names shall be seperated by spaces. A checkbox indicates whether the primary C source file name derived from the Main file name setting should be included or not. The popup will be closed by pressing <Enter> in the entry field.
  - The entry Assembler source file(s) works similar except there are no default assembler sources to be included. Note that assembler source files get the suffix `.S` (capital letter s) which means they are being pre-processed by the C preprocessor, so `#include` etc. will work. A lower-case letter `.s` suffix is considered to be a temporary compiler output file, and should not be used here.
  - Using External RAM options, several possible variants to use external RAM can be selected. This is internally handled by editing the EXTMEMOPTS macro which eventually gets added to the LDFLAGS during linking. The options are to either use external RAM for both, variables (i. e. sections .data and .bss) as well as for the heap (dynamic memory for `malloc()`), or to leave variables in internal memory and use the external RAM only for the heap. In both cases, the stack will always remain in internal memory; this is the fastest way, and some AVR MCUs have hardware bugs so they would not work when the stack is located in external RAM. It can be selected whether the external RAM should start at the lowest possible memory location (right behind the internal RAM), or at a different memory address. Several common memory sizes can be chosen from. Obviously, these options are only accessible for MCU types that do have an external memory interface.
  - The entry Debug format selects one out of the following options:
    - ELF/stabs ELF object files with stabs debugging information are currently the native way to debug under Unix and/or GDB. This includes any GDB frontend, like Insight or DDD.
    - AVR-COFF Selecting this format will internally also generate an ELF/stabs file, but change the Makefile to subsequently convert the ELF file into a COFF file that adheres to the originally Atmel AVR COFF file format specification. This file format is understood by AVR Studio up to 3.x, and VMLAB up to 3.9.
    - AVR-ext-COFF The conversion from internal ELF to COFF will be tuned to produce a file according to the later AVR "extended" COFF specification by Atmel, understood by AVR Studio 4.07 and above, and VMLAB 3.10 and above.
    - ELF/DWARF-2 Create an ELF standard object file with DWARF-2 debug information. This is the proposed standard debug format for ELF. It is currently Beta, the GNU tools are slowly changing towards that standard (though it is not yet known whether AVR-GDB will already fully understand the format yet), and Atmel has released a beta ELF/DWARF-2 parser for their AVR Studio.
- AVRdude options
  - The entry Programmer allows the selection of the programming hardware (parallel port "dongle", or serially connected hardware).
  - The entry Port selects the serial or parallel port AVRdude is going to talk across. This menu item might be missing on some operating systems where no default ports are known.
- Miscellaneous
  - By default, the editor widget is read-only, and can only be modified by the menu entries mentioned above. By checking the Enable Editing of Makefile checkbox, this restriction can be lifted, and the widget can be used as a simple standard text editor for the generated Makefile. Note that the menu operations mentioned above are not guaranteed to work on arbitrary input texts since they search for certain patterns in order to implement their functionality, so manual editing should always be used as a last step before eventually saving the generated Makefile.