Compilers

Located as a subdirectory directly under the main enigma-dev directory,
this folder contains a subdirectory for each of the platforms on which
LGM can run (Windows, Mac, and Linux). Each of these subfolders contains
eYAML files specifying available compilers for that
system. In these files should be important information for calling
relative toolchain executables. The
most common eYAML file will probably be gcc.ey, since GCC is probably
the most common compiler for all platforms.

This format does not specify the location of a makefile to be used.
Including the correct makefile is the job of the general-purpose
makefile under SHELL/. Makefiles for it to include
will be in the folder Makefiles/ in its own
directory. This folder will have an identical structure to this
Compilers/ folder; the makefiles will be named corresponding to the
eYAML filenames, without the .ey extension.

Fields

This specification should cover all our needs. Notice that, again, the
filename itself (sans the extension) is the identifier for the compiler.

• Name will specify the human-readable name of the compiler. (The
  filename specifies the machine name).
• Native is implemented mostly for the IDE; it states "Yes" or
  "No" for whether the compiler compiles for the current OS.
• Maintainer just names the poor sap in charge of making sure the
  compiler works. It's for those who read it, or to be displayed in
  the IDE as details.
• Description is entirely optional, but can be used to
  describe/differentiate one compiler from another, or may be omitted
  altogether. For IDE.
• Target-platform gives the specific, singular device or operating
  system for which this file describes a compile toolchain.

• path Gives a list of paths to be prefixed to the system PATH
  variable. The format of this list is specific to each platform, not
  to each compiler. This field will primarily just be passed to the
  makefile, not used by the Plugin or
  ENIGMA, as that path information will already
  be accounted for in the make field.
• make denotes the path to the toolchain executable for this
  compiler that parses makefiles. This must either be a
  fully-qualified path, or must be the first lookup under the system
  PATH.
• defines specifies the toolchain executable and the parameters
  required to produce a list of all macros defined by this compiler
  implementation. This is for source parsing purposes.
  • If this command utilizes the keyword $blank, a path to an
    empty file will be passed in its place.
  • If this command utilizes the keyword $out, a path to the
    desired output file will be passed.
    • If it does not specify $out, the contents of the standard
      output streams will be redirected to the desired file
      instead.
  • The path to the executable must be the first term in the line
    (you must quote it if it contains spaces).
    • Like make, the path to the executable must either be
      fully qualified, or the executable must be the first lookup
      result in the system PATH.
• searchdirs is identical to defines, except the toolchain
  executable specified with the commands passed to it is expected to
  yield a list of all search directories.
  • If the output from this program is not exclusively a list of
    directories, separated by newlines, the following attributes can
    be used to isolate them
    • searchdirs-start names the last line to be ignored. If
      this is not specified, the beginning of the file is not
      ignored.
    • searchdirs-end names the first line to start ignoring
      again. If this is not specified, no more lines are skipped
      in the file.
• resources specifies the file to which resources are expected to
  be written.
  • The keyword $exe can be used to insert the full path to
    the output executable, or $exename can be used to get only
    the filename part (including any extension).
    • This is the filename specified by the IDE for output.
• cppflags gives any flags that are necessary to compile for this
  platform in general.
• cflags is the same as cppflags, but is passed exclusively to the
  C-compiler for .c files.
• links names any linker parameters needed to compile for this
  platform in general.

• Build-Extension gives the extension of the produced game file.
• Build-Type specifies whether the extension represents a File or
  Directory object. The default is File.
• Run-Output specifies where the file is written by default. This
  is where the game will be run from. The special value
  $tempfile lets the IDE pick.
• Run-Program specifies the name of the binary invoked to run the
  game. This is typically just the special object $game unless
  the game is being emulated for a different platform.
• Run-Params: The parameter passed to the above binary. In the
  case of an emulator, $game can be used here as well. Bear in
  mind, $game gives the escaped path to the produced module.

Original Proposal

The following information was specified as the desired fields for the
original specification, as proposed by
User:Tgmg. Later, we revised the idea and came
up with what we are currently using (above).

• Bin Path. A set of paths to be added, as-is, to the PATH
  variable. They will be added at the very beginning to ensure
  precedence over other paths in the system PATH variable.
• Data file name. The location of the file to write the resources
  such as sprites and background to. Some platforms append this to the
  end of the executable, but other platforms cannot do this, so for
  those platforms it will write to a .data file in a specific
  location.
• MakeFile Path. The location of the makefile for this platform,
  probably located under MakeFiles/Platform/OS/Makefile, but may be
  located elsewhere. The file that it points to should contain the
  following targets:
  • Compile for compiling enigma itself for the platform.
  • Game for compiling the game for the platform.
  • Run will be called when the compiling has completed (which
    will setup emulators etc and run the executable)
  • Clean for deleting all the object files and executables so
    that the directory is clean for either deletion or, more
    usually, so that the next compile will be completely fresh.

How it links

I'm just gonna leave this here to kinda remind myself of how this system
works, although I can probably read about it in
About.ey.

In order to populate the API Compilers dropdown, we first obtain the
current operating system, one of Linux, Windows, or MacOSX. Then we
iterate through Compilers/$(OS)/*.ey as our active list of compilers
for our operating system. They specify which platform they compile FOR
with the Target-platform field, logically. This Target-platform will
then serve as a kind of linker middle-man for when we try get the list
of Platforms, think of it as a Platform Category.

Next, to populate the Platforms dropdwon, we iterate through
ENIGMASystem/SHELL/Platforms/(.*)/About.ey looking for anything that
has a Build-platforms list that includes one of our Platform Categories.
This then connects a link between that Platform and that Compiler (and
since Build-platforms is a list, it can resultantly connect to multiple
Compilers), so that the Platform will be available for selection when
any of its Compilers is selected.

From there, all the other API systems follow a standard Dependencies
system to determine which is available when. Currently, each of the
different API system categories is hard-coded (not dynamic).