Skip to content

Modules Proposal

Jump to bottom
starkos edited this page Apr 10, 2021 · 2 revisions

⚠️ We have a new website! Visit now for the most update to date documentation.
       This wiki is no longer being maintained.

I am just getting started with this! I am building out my first module, and will continue to update this guide as I go.

After some good feedback from the initial extension proposal, I'm making some changes to the approach. Everything in the Extending Premake is still valid; now I'm going to integrate it with Lua's own modules and set some conventions about how to create, use, and share them.

I am in the process of developing an XCode module which you can check out as proof-of-concept.

Introducing Modules

Use Lua modules as the basis. Folks you know Lua will be familiar with them, and we can use the require() function and the built-in package functionality.

A Premake module will be packaged as a folder named after the module, and containing a Lua script of the same name.

xcode/xcode.lua

This allows a module to be delivered as multiple files, instead of cramming everything into one script.

Using a Module

Fetch the module by pulling it from its source code repository.

$ cd (somewhere)
$ git clone https://github.com/premake/premake-xcode.git xcode

Modules need to be placed somewhere on the search path in order to be found. The built-in search paths are currently:

  • A .premake folder in the user's home directory
  • A modules folder in the current working directory
  • A modules folder in the same directory as the Premake executable
  • In the user's Library/Application Support/Premake directory (Mac OS X)
  • In the /usr/local/share/premake directory
  • In the /usr/share/premake directory

Creating a Module

Modules generally should get their own source code repositories. This allows anyone to spin up a new module, and provides more fine-grained control over who is allowed to contribute to it. I guess the repository should have the same name as the module itself, to make checkouts simpler? At the same time, folks will likely want to somehow indicate the function (Premake) of the code, in case they want to target other stuff. And really, in the end probably doesn't matter. But it needs to have a common name so that other modules can find it! So I guess you just put it into the directions then? Canonical name?

The current Premake-ext team has two repositories named "codelite" and "d". This convention makes sense for "official" repositories. It shouldn't matter what other people want to call their extensions.

Core Modules

I would like to carry this same architecture over to the main Premake distribution, splitting it up into a core that manages script parsing and configuration building, and a collection of modules which create outputs from those configurations.

Once set up this way, any module that becomes popular and stable enough could be easily dropped into the official releases (once I figure out how to embed them in the executable easily).

To support this, I will likely rearrange the Premake source code repositories into a "shell" repository that includes the core and all of the core modules as Git submodules. Maybe something like:

premake-main
	core
	modules
		vstudio
		gmake
		xcode

Cloning premake-main will automatically clone all of the submodules as well, and Git will take care of associating submodule versions with changesets.

Spinning the exporters out to their own modules in this way opens the door for also moving them into their own repositories, which would enable more people to have contributor priviledges.

Open Questions

  • How do we reconcile documentation, issue tracking, and the like across multiple module repositories? How do people know where to look for information, or to file a bug report?

    • I'm thinking that the main repository (see "Core Modules" above) would have the documentation and the issue tracker for everything in core. For third-party modules, I think it will be intuitive enough to look for documentation and issue tracking from the same repository where you downloaded the module in the first place.

  • How are modules unit tested?

  • How are core modules loaded in debug builds? How are they embedded into release builds?

  • How do people find modules?

    • Could request inclusion in premake-ext (rename to "Premake Modules") GitHub organisation?
    • Keep a wiki page somewhere?

  • How to manage releases and track dependencies between modules?

    • How to tracking compatibility between core and modules?
    • How to manage tags and versions across modules?
    • Suggest following Drupal convention of core_version-module_version, e.g. 5.x-1.0
Clone this wiki locally