Compilers - hpgDesigns/hpgdesigns-dev.io GitHub Wiki

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).