View source for LDT/User Area/Execution Environment file format

=Execution Environment=

An Execution Environment, which may also be referred to as EE, is file containing information about the environment on which a Lua application will be executed.

So, if you want to enable some IDE features (autocompletion, code documentation, ...) for a given execution environment (Lua 5.1, Corona, mihini, Gideros, ...) you can create your own custom EE, there are just ''few rules'' to match the type of the file and its inner structure.

You could share your execution environment [[LDT/User_Area/Available_Execution_Environments|here]].

==File format==

An EE is simply a regular ''.zip'' file.

==File structure==

To be a ''valid EE'', a ZIP file root must respect the following tree structure.

* <code>/</code>
** <code>api.zip</code>
** <code>docs/</code>
*** <code>index.html</code>
** <code>*.rockspec</code>

<code>api.zip</code> is a regular ZIP archive containing Lua API files (extension ''.luadoc'') written with the [[LDT/User_Area/Documentation_Language| right format]].<br>
You could generate these api files from your source code (lua and C)  with [[LDT/User_Area/LuaDocumentor|LuaDocumentor]] command line tool.(perhaps one day LuaDocumentor will be able to generate the complete execution environment) <br>
'''Note on globals''': All the globals variable you will defined in global.lua will be considered as preloaded global variables, this means they will be always available in LDT autocompletion.


<code>docs/</code> is a ''folder'' containing <code>html</code> documentation files. <code>index.html</code> is the file opened by LDT when user ask for EE documentation. (see [[LDT/User_Area/LuaDocumentor|LuaDocumentor]])

<code>*.rockspec</code> enable to specify information about an EE, it is strongly inspired by the [http://luarocks.org/en/Rockspec_format Rockspec format]. So far, following fields have been added to match LDT needs:
*<code>api</code>
*<code>documentation</code>
*<code>flags</code>
You may have noticed that <code>api.file</code> is set to <code>'api.zip'</code> and <code>documentation.dir</code> to <code>'docs'</code>. '''Do not change''' those values in the *.rockspec you write, it will have '''no effect'''.<br/>
'''As I am writing, all parameters are hard coded, except:'''

* <code>package</code>
* <code>version</code>

It is temporary, we will soon handle all *.rockspec settings. This why you '''must write valid *.rockspec''' to be compliant with up coming versions of LDT.

'''Since 1.1:'''
*<code>templates/</code> (optional)
**<code>default/</code>
If a ''Lua Project'' is created using an ''Execution Environment'' with the ''Create a default template ready to run'' option checked, it will be filled with files and folders under <code>templates/default/</code>. In the future, it will be possible to select different templates defined in the <code>templates/</code> folder. For now, only the <code>default/</code> sub folder is supported. By default, the buildpath of your project will only contain the folder ''src'', but it can be customized in the manifest.

'''Since 1.3:'''
*<code>grammar/</code> (optional)
The grammar of lua on which the execution environment is built.
This information is used by LDT to select the right grammar automatically at [[LDT/User_Area/New_Noteworthy/New_Noteworthy_1.3#Lua_5.2_Project_Creation|project creation]].

===A sample of EE manifest===
<source lang="lua"> 
package = "lua"
version = "5.1"
grammar = "lua-5.1"
flags = { ee = true }
description = {
  summary = "Lua 5.1 Execution Environment",
  detailed = [[ Lua 5.1 Execution Environment Support]],
  licence = "MIT",
  homepage= "http://www.lua.org/manual/5.1/manual.html"
}
api = {
  file = "api.zip"
}
documentation = {
  dir="docs"
}
templates = {
  default = {
    buildpath = {"mysrc","mysecondsrc"},
    openfile = "mysrc/myfile.lua"
}</source>

'''Note on templates: '''
The ''templates'' node is optional. If not set, a default one will be used with a ''src'' folder in source path and a default ''main.lua'' file.<br>
The ''buildpath'' node is a list of folder project relative paths to be included in the buildpath of the created project. To add the whole project in the buildpath add ''/'' in the ''buildpath'' list. An error will be throw if the ''buildpath'' list contains a subfolder path to a previous path in the list (e.g. you can't have a list like that: <code>{"src/", "src/myfolder"}</code>).<br>
The ''openfile'' node is a project relative path to the file to open when the project creation is finish ( by default ''src/main.lua'').