The final output files are located in directories based on the CONFIG and BOARD parameters. The SETTINGS_FILE and other options have no bearing on output file locations.

If CONFIG is defined, then the final output is placed in g2core/build/$(CONFIG)-$(BOARD)/ and the intermediate files (.o "object files", makefile "dependency files", etc) required to build the final output files are stored in g2core/bin/$(CONFIG)-$(BOARD)/.

Note: See Other make options below for important options to add to a make command line stored in a GUI such as Xcode or Atmel Studio.

The BOARD setting is required, however a default value is provided if you provide a CONFIG value.

The make command line should specify a CONFIG, which provides at least a default BOARD and a default SETTINGS_FILE. Even if CONFIG is specified you can override the default BOARD and SETTINGS_FILE.

All of these are case sensitive. Example:

• For a Shapeoko dual-Y-motor configuration using a g2v9k call make with CONFIG=ShapeokoDualY:

• For a Shapeoko dual-Y-motor configuration using a custom board called CustomBoard:

1. To enter the debugger, add debug

To save time the makefile will only compile the files needed when something changes. Sometimes you need to clean out all the old compiled intermediate files. There are two ways to do this:

1. The nice way: Add clean to the end of your command line (replacing debug or debuggy if it was there).

   📓	make …​ clean must have the same BOARD/CONFIG options as the make did in order to locate the files. See Output Files for more explanation as to how it finds those files. SETTINGS_FILE can be omitted from the clean line.

2. The not so nice way:🔨 Delete the directories g2core/bin and g2core/build from your repo.

   ⚠️	Make sure you don’t accidentally throw away board!

   • This removes all of the build files and intermediates for all configurations.

There are a few other command line make options to be aware of:

• VERBOSE - set this to 0 (for "quiet," which is the default), 1 (to show commands executed in full), or 2 (the same as 1 plus additional Makefile debug reporting).

  ❗	For all make command lines stored in GUIs (Atmel Studio, Xcode), you should use VERBOSE=1

• COLOR - set this to 1 (the default) or 0 (to not use terminal escape sequences to make the voluminous output more readable)

  ❗	For all make command lines stored in GUIs (Atmel Studio, Xcode), you should use COLOR=0

• OPTIMIZATION - set this to the -O value for gcc. Generally we use OPTIMIZATION=3 as the default, but may use OPTIMIZATION=s if we want to save flash space.

  ⚠️	This should NOT be hard coded into a GUI make command unless it’s deemed necessary — use the default.

  ⚠️

  Generally, if you set it to below 2 the code will be huge and cannot fit on any of the target processors. Said again, more directly: this cannot be set to 0 or the code will not fit on the processor. We rely on the optimizer to make the code perform reasonably and be a reasonable size. This has a minor negative impact on debugging, but it’s manageable.

Compilation is managed by this makefile hierarchy:

• ./g2core/Makefile Main project makefile invokes:

  • ./Motate/Motate.mk invokes MotateUtilities.mk and kicks off the Board makefiles:

    • ./g2core/board/xxxxxx.mk is the makefile for a specific board, and may also include a baseboard makefile

In the g2core project structure (covered here) there is a boards.mk file and several files and directories under board/ for each board type.

• boards.mk - This file is what is included by the Motate Makefile. It’s contents are primarily handling CONFIGs. At the end it has this important line:

  # Note: STAR=* -- a workaround for a Makefile glitch.
  include $(wildcard ./board/$(STAR).mk)

  • This line imports (in relatively random order) any file that ends with .mk that’s directly inside the board/ directory.

• board/*.mk - Each .mk file inside board/ has the opportunity to define what happens when a BOARD has a specific value. We’ll cover how to do that shortly.

• board/*.gdb - This is the GDB startup file for each board.

  • It is located from inside Motate as "${BOARD_PATH}.gdb".

Each BOARD sets a few important values:

• BASE_BOARD - This is used later to know which settings to use for a range of boards. We show how to create that next.

  💡	Even if you only have one board revision, it’s still good practice to break BASE_BOARD and BOARD out so you can revise later.

• DEVICE_DEFINES - This is where you pass defines directly into the code (as if they were #defined).

  ❗	You want to make sure you use += to add to DEVICE_DEFINES, not just = or =:. There are other places to add to DEVICE_DEFINES as well, and some are called before boards.mk is.

  • You need to define at least two values: MOTATE_BOARD and SETTINGS_FILE

    • MOTATE_BOARD (in DEVICE_DEFINES) - This is used in locating the pinout file, in the form of ${MOTATE_BOARD}-pinout.h. This is generally equal to BOARD, but may be different.

      ❗

      On case sensitive operating systems, such as linux, ${MOTATE_BOARD}-pinout.h must match the pinout file name exactly. On OS X, which is usually not case sensitive, this will match with different case. Please be sure to check the case of this and the file. Better yet, just always use lowercase for both.

    • SETTINGS_FILE (in DEVICE_DEFINES) - this is usually just passed through:

      DEVICE_DEFINES += SETTINGS_FILE=${SETTINGS_FILE}

Each BASE_BOARD sets a few important values:

• _BOARD_FOUND - Just set it to 1: _BOARD_FOUND = 1 - this tells the calling Makefile that the board is configured.

• FIRST_LINK_SOURCES - Without spending too much time talking about linking order and such — and that is important, this value tells the compiler which files to link first, and it is in order.

  ❗	Make sure to only add to this value with +=! Normally main.cpp will already be on that list and will be first.

  💡	Use one of the other .mk files as an example. Generally this only refers to files in Motate, and will be the same for all processors of the same type.

• CHIP - This sets the main processor used by the board. This must be supported by Motate.

  ❗	CHIP must be made available to the shell environment after it’s set with an export CHIP.

  💡	Again, use one of the other .mk files as an example. If Motate supports it there’s likely already another board with the CHIP you are using.

• CHIP_LOWERCASE - This is the same as CHIP but lowercase. This is used by Motate to locate some vendor files. CHIP_LOWERCASE does not need to be exported.

• BOARD_PATH - This setting sets where the project will locate the gdb file (as "${BOARD_PATH}.gdb"), and is used to find files such as hardware.h when this board is being used.

  ❗	The BOARD_PATH will not be added to the include search path until it is added to SOURCE_DIRS!

  💡	Often BOARD_PATH is equivalent to ./board/${BASE_BOARD} — but it doesn’t have to be.

• SOURCE_DIRS - This setting tells Motate where to find files to compile (.c, .cpp, and *.s will be compiled and linked in), as well as where to search for included header files.

  ❗	Make sure to only add to this value with +=! This is used to generate the list of all files to be compiled, and there are several other places that add to this list.

  💡	This is the place where you add the directories of devices under the device/ directory to be included in the compile.

• PLATFORM_BASE - The PLATFORM_BASE value is the path (without the .mk) to the platform definition file provided by Motate to configure compilation for this processor.

  ❗	The last line of the BASE_BOARD definition must be: include $(PLATFORM_BASE).mk