umake Files

Please visite www.imakecircuits.com


My name is umake, not GNU make
----------

umake is a tool that I've created in linux so I can call different compilers
from a single command line.  Let me rephrase that: umake is  a simple bash
script with a bunch of Makefile template files that act as a front-end for GNU
make (that was much simple). Let's do some GNU make slavering do all our
bidding.

I'm not an adept of the compiler IDE such as MPLAB or Keil uVision, first
because I need to include all these pretty windows applications on my linux
distro (if they even work with wine), second, work with there stupid interfaces
and last, did I already mention that I was a linux fan... So now you asking me
what's the advantage of using a command line tool like umake, here a short list
of what it can do:

   * Fetch recursively all source files from path instead of adding them one by
     one.
   * Build for different architectures by choosing in a list of target.
   * Possibility to exclude files or folders.
   * Use the versatility of GNU make by creating your own rule in your Makefile
     template.
   * Build dependencies so only modified files are build instead of whole
     project.


If I'm right, the first and the last features should have gotten you attention.
Yes, yes, umake can save you time...



It got some flaws
----------

You cannot have 2 different source files with the same name as one will
overwrite the other, even if they are in different folders. This is the case for
the folders name also, you cannot have 2 folders of the same name in your
project.

This is something I should fix but I didn't needed to. To tell the truth, I
simply avoid it...



Get this MIGHTY script working
----------

First, the umake compressed package should be unpacked in your $HOME, well that
what I do, feel free to change it.

To be useful as a compiler script, we should be able to call this baby from
anywhere on your linux distro. Two lines of bash script are needed for that in
your ~/.bashrc file:

   export PATH=$PATH:~/LAG/pkg_umake
   export UMAKE_TEMPLATE_PATH=~/LAG/pkg_umake
   

The first line is to include umake in your application searching path, the
second line is internal to the script and determine the path to the Makefile
template files. Included templates in the package are in the same folder as the
script.

Well, that's it, who said linux was complicated? Now you should be able to call
umake anywhere and get the message "*** Makefile.cfg is missing". Now it's
obvious that we need to talk about that configuration file.



Makefile.cfg, my precious...
----------

The file Makefile.cfg is used to enter the project configurations for umake,
in fact, umake won't work without it. Let see a simple example of what your
Makefile.cfg could looks like and comment on it.

   #!/bin/bash

   # umake configuration file.

   # Please, never include / after folders or files name.
   # Also, never include ../ in the SRC_PATH.

   aszPlatforms=(
      avr_gcc_libc_atmega48
      keil_c51_ds89c450
      all
   )

   if [[ -n $1 ]]
   then
      MakefileConfigs=(
         MAIN=testcases +
      )
   fi

   case $1 in
      avr_gcc_libc_atmega48)
         MakefileConfigs=(
            ${MakefileConfigs[*]}

            CC=avr-gcc +
            OBJCOPY=avr-objcopy +

            MCU=atmega48 +
            ADD_CFLAGS=-O2 +

            INCLUDE_PATH=                           \
               ../../src                            \
               ../../../pkg_uFW/src                 \
               /opt/cross/avr/include +
            SRC_PATH=                               \
               ../../src                            \
               ../../../pkg_uFW/src +

            EXCLUDED_FILES=                         \
               uFW_serial1.c +

            EXCLUDED_FOLDERS=                       \
               ../../../pkg_uFW/src/lib/graphic     \
               ../../../pkg_uFW/src/lib/lcd         \
               ../../../pkg_uFW/src/lib/ntsc        \
               ../../src/lib/lcd +
         )
         ;;

      keil_c51_ds89c450)
         MakefileConfigs=(
            ${MakefileConfigs[*]}

            CC=wine cx51.exe +
            LD=wine lx51.exe +
            AS=wine ax51.exe +
            OBJCOPY=wine ohx51.exe +

            INCLUDE_PATH=                           \
               ../../src                            \
               ../../../pkg_uFW/src                 \
               ~/.wine/drive_c/Keil/C51/INC +
            SRC_PATH=                               \
               ../../src                            \
               ../../../pkg_uFW/src +

            EXCLUDED_FILES=                         \
               uFW_lcd.c                            \
               uFW_int.c +

            EXCLUDED_FOLDERS=                       \
               ../../../pkg_uFW/src/lib/graphic     \
               ../../../pkg_uFW/src/lib/ntsc        \
               ../../../pkg_uFW/src/lib/lcd         \
               ../../src/lib/lcd +

            LIB=                                    \
               ~/.wine/drive_c/Keil/C51/LIB/C51L.LIB +
            ASMSRC=                                 \
               ../../src/startup.a51                \
               ../../../pkg_uFW/src/basic/uFW_nop.a51 +
         )
         ;;
   esac


Let's begin by the aszPlatform variable. What you can see in the list is that I
have put the word 'all' to tell umake to build all the targets from that list
if  'all' is selected, this is coded in umake. Also, names from the list can be
anything as long as the first part of the name match the Makefile template file 
name, but we will come back on this in the template section.

The second most important variable is MakefileConfigs. This is also a list and
it contains the Makefile variables to help in the compilation. Each variable
can have multiple arguments and the + sign must be added to tell umake that the
variable is done.

Makefile.cfg is sourced twice by umake. The first time is to throw at you a
nice list of targets defined by the aszPlatform variable. The second time is
done right after you select the target. The script now know the Makefile
template to fetch and the various variables from the case statement that will
be included in that Makefile.

As I said, there is some important variables to be filled depending of the
project, here's the currently supported by the Makefile templates included with
umake:

   * CC
     C compiler to be used for the target.

   * LD
     Linker to be used for the target.

   * AS
     Assembler to be used for the target.

   * OBJCOPY
     This would be he utility to create your HEX file for the target.
     
   * FLASHER_PORT
     Defines the serial COM to be used when flashing the device (AVR_GCC_LIBC
     and KEIL_C51).

   * FLASHER_BAUD
     Defines the baud rate to use when flashing the device. The flasher used is
     dsflasher that I have compiled for diferent baudrate and named them
     dsflasher_<baud> (KEIL_C51).

   * FLASHER_MCU
     Defines the MCU to be used when flashing with avrdude (AVR_GCC_LIBC).
     
   -----  

   * LIB
     Libraries to include in the project.

   * LIB_PATH
     Paths to the project libraries.

   * ASMSRC
     Assembler source files for KEIL_C51.

   * SRC_PATH
     Paths to the project sources.

   * INCLUDE_PATH
     Paths to the project headers.

   * LKR
     Linker file for MPLAB_C18.

   * LKR_PATH
     Paths to the project MPLAB_C18 linker files.

   -----
   
   * MAIN
     This is your project name and also the name of your main project file
     (without the extension .c) that will contain your main().

   * MCU
     Microcontroller name for the AVR_GCC_LIBC and MPLAB_C18 project.

   * ADD_CFLAGS
     Add custom compiler flags to the project.

   * ADD_LDFLAGS
     Add custom linker flags to the project.

   * ADD_ASMFLAGS
     Add custom assembler flags to the project for KEIL_C51.

   * EXCLUDED_FILES
     Files to be excluded from the project on the automatic sources fetching.

   * EXCLUDED_FOLDERS
     Folders to be excluded from the project on the automatic sources fetching.


Those variables are the one I use but if you create your own Makefile
templates, you can add as many variables as you need as long as you respect the
GNU make syntax and you include them in the MakefileConfigs variable.


My own template
----------

Creating your own template is easy, in fact, it is a standard Makefile from GNU 
make. You can have all the documentation of make by clicking here. I will not
tell you how to write a makefile, instead, I will tell you how umake is using
the Makefile. If you need any good starter example, you can have a look the the
templates that comes with umake in the download section.

Let's begin by the files names. umake is looking for files that begins with
'template_' in the folder stored in UMAKE_TEMPLATE_PATH variable. The next
characters after that is the compiler name. An example should looks like
template_keil_c51.

When you enter a template in the aszPlatforms list from the Makefile.cfg file,
it is the compiler name you enter. But, as you may have noticed in the previous
post from the Makefile.cfg code example, you may add what I call a reference for
yourself in the case you compile on different hardwares with the same compiler.
The reference must start with an underscore and can have whatever character you
want after, it is only shown on the screen and have no other purpose. My
reference are usually the microcontroller part number. So, in your aszPlatforms
list, you should have something like keil_c51_ds89c450. You never include
'template_' in the list as umake remove it.


Where all the files go?
----------

VPATH is the secret. OK, before we continue, you really need to know how I work
because umake have been coded for my computer… sorry for those that don’t agree.
Here is the folder tree I’m using:

   ~/LAG
      /pkg_uFW
         /doc
         /src
      /pkg_umake
      /prj_uFW
         /hex
         /src
         /testcases
            Makefile.cfg


Every project I do begin with the prj_ prefix and have the folders structure you
see there. I put my Makefile.cfg in the /testcases folder and all project
sources in /src. The /hex forder contains all the .hex files output when I issue
the command umake hex from the /testcases folder (I really like those rules).

Remember in another post when I mentioned the aszPlatform list, well, when you
compile a target from that list, a folder will be created in /testcases with the
name of your target. Every generated files from the compilation will be dropped
in that new folder thanks to the magic of VPATH that all included template files
from the umake package use.

The Makefile for your target will also be copied and executed in that folder by
umake. This is important to know when you will use relative path for your
headers or sources files as you need to start counting down your folder from
that taget folder.


MPLAB C18 under linux
----------

It is nice to have umake, but to make this work you need toolchains that are
supported by the script. Let's begin by maybe the favorite of the crowd, citizen
of the net, behold MPLAB C18. Weird, that sounded like Spartacus.

Installing the MPLAB C18 toolchain is a breeze as you can simply take another
installation from windows and copy the folder right into your linux distribution.
I like to keep my things clean so I put all my toolchains in /opt, I'm just that
complicated. So I suggest you copy your installation in /opt/c18. If you need to
install it, use wine and then copy it. Don't worry for the registration as it is
copied also.

Notice that I don't mention anything about the crappy MPLAB IDE, that's right,
don't install it. Even if we wanted to install the IDE, umake don't need it and
the wine support doesn't quite do the job.

Now edit the file ~/.wine/system.reg and search for the word PATH (case
sensitive), this is the path environment variable of windows, and add
;z:\\opt\\c18\\bin to it so you can call your executables anywhere in your
distro.

In my search for the perfect MPLAB C18 compiler in linux, I was having trouble
with the error message 'could not find definition of symbol x in file y.o'.
Later I found out that my openSUSE 11.1 did not have the latest wine version.
Bottom line, I strongly advise having at least the wine version 1.3.1 package
and up as my problem was gone.

Right now, if you execute the command wine mcc18.exe, you should have the
compiler running.

In your Makefile.cfg file, you should use these toolchain variables in the
MakefileConfigs list:

   CC=wine mcc18.exe +
   LD=wine mplink.exe +
   OBJCOPY=wine mp2hex.exe +


Keil C51 under linux
----------

My mother always said to me: "If you did not have wine, you would have been a
miserable Windows user", she was right you know, thanks mom to tell me what is
so obvious. Well you guessed right, Keil C51 run perfectly under linux, even
the IDE, thanks to the magic of wine.

Keil needs to be installed with wine and you can't move the installed files as
your license key will stop working. I installed my copy in c:\Keil, feel free
to choose a more suitable folder name, but I said in another post that I want
all my toolchains in /opt, what to do? What I'm suggesting is to create a
symbolic link for c:\Keil in /opt: ln -s ~/.wine/drive_c/Keil/C51 /opt/c51.

Now to enable this baby from being called from everywhere, edit the file
~/.wine/system.reg and search for the word PATH (case sensitive) and add
;c:\\Keil\\C51\\BIN to the variable.

At this time, if you execute the command wine cx51.exe, you should have the
compiler running.

Set to toolchain variables in MakefileConfigs list from your Makefiles.cfg file:

   CC=wine c51.exe +
   LD=wine lx51.exe +
   AS=wine ax51.exe +
   OBJCOPY=wine ohx51.exe +