Difference between revisions of "Koneki/LDT/User Area/Execution Environment file format"

From Eclipsepedia

< Koneki‎ | LDT
Jump to: navigation, search
(File structure)
(File structure)
 
(3 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
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.
 
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 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 a ''few rules'' to follow the type of the file and its inner structure.
+
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 [[Koneki/LDT/User_Area/Available_Execution_Environments|here]].
 
You could share your execution environment [[Koneki/LDT/User_Area/Available_Execution_Environments|here]].
 
'''Since 0.9M2:''' When a new Lua Project is created, a default main.lua is also created which is containing some code. As this code can be dependent of the Execution Environment associated with the project. It's now possible to add default main.lua in your Execution Environment. So when a project is created using an Execution Environment the created project is filled using the Execution Environment's main.lua file.
 
  
 
==File format==
 
==File format==
Line 23: Line 21:
 
** <code>*.rockspec</code>
 
** <code>*.rockspec</code>
  
<code>api.zip</code> is a regular ZIP archive containing Lua API files written with the [[Koneki/LDT/User_Area/Documentation_Language| right format]].<br>
+
<code>api.zip</code> is a regular ZIP archive containing Lua API files (extension ''.luadoc'') written with the [[Koneki/LDT/User_Area/Documentation_Language| right format]].<br>
 
You could generate these api files from your source code (lua and C)  with [[Koneki/LDT/User_Area/LuaDocumentor|LuaDocumentor]] command line tool.(perhaps one day LuaDocumentor will be able to generate the complete execution environment) <br>
 
You could generate these api files from your source code (lua and C)  with [[Koneki/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 your will defined in global.lua will be considered as preloaded global variables, this means they will be always available in LDT autocompletion. Now, others globals declared outside the global.lua file won't be available in the auto-completion as they are not considered as preloaded by the environment but may be initialized sometime during the runtime, this behavior will be enhanced, see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=414315 BUG-414315].
+
'''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 [[Koneki/LDT/User_Area/LuaDocumentor|LuaDocumentor]])
+
<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 [[Koneki/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>*.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:
Line 34: Line 32:
 
*<code>documentation</code>
 
*<code>documentation</code>
 
*<code>flags</code>
 
*<code>flags</code>
*<code>template</code>
 
**<code>main.lua</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/>
 
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:'''
 
'''As I am writing, all parameters are hard coded, except:'''
Line 44: Line 40:
 
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.
 
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 0.9M2:'''
+
'''Since 1.1:'''
*<code>template</code>
+
*<code>templates/</code> (optional)
**<code>main.lua</code>
+
**<code>default/</code>
If a new Lua Project is created using the Execution Environment, the created project will be filled using the given main.lua. As this file is optional, if the main.lua file is not found in the Execution Environment, the project will be filled with a lua generic main.lua.
+
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.
  
 
===A sample of EE manifest===
 
===A sample of EE manifest===
<code><pre>
+
<source lang="lua">  
 
package = "lua"
 
package = "lua"
 
version = "5.1"
 
version = "5.1"
 
flags = { ee = true }
 
flags = { ee = true }
 
description = {
 
description = {
  summary = "Lua 5.1 Execution Environment",
+
  summary = "Lua 5.1 Execution Environment",
  detailed = [[ Lua 5.1 Execution Environment Support]],
+
  detailed = [[ Lua 5.1 Execution Environment Support]],
  licence = "MIT",
+
  licence = "MIT",
  homepage= "http://www.lua.org/manual/5.1/manual.html"
+
  homepage= "http://www.lua.org/manual/5.1/manual.html"
 
}
 
}
 
api = {
 
api = {
  file = "api.zip"
+
  file = "api.zip"
 
}
 
}
documentation ={
+
documentation = {
 
   dir="docs"
 
   dir="docs"
}</pre>
+
}
</code>
+
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'').

Latest revision as of 09:23, 11 April 2014

Contents

[edit] 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 here.

[edit] File format

An EE is simply a regular .zip file.

[edit] File structure

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

  • /
    • api.zip
    • docs/
      • index.html
    • *.rockspec

api.zip is a regular ZIP archive containing Lua API files (extension .luadoc) written with the right format.
You could generate these api files from your source code (lua and C) with LuaDocumentor command line tool.(perhaps one day LuaDocumentor will be able to generate the complete execution environment)
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.


docs/ is a folder containing html documentation files. index.html is the file opened by LDT when user ask for EE documentation. (see LuaDocumentor)

*.rockspec enable to specify information about an EE, it is strongly inspired by the Rockspec format. So far, following fields have been added to match LDT needs:

  • api
  • documentation
  • flags

You may have noticed that api.file is set to 'api.zip' and documentation.dir to 'docs'. Do not change those values in the *.rockspec you write, it will have no effect.
As I am writing, all parameters are hard coded, except:

  • package
  • version

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:

  • templates/ (optional)
    • default/

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 templates/default/. In the future, it will be possible to select different templates defined in the templates/ folder. For now, only the default/ 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.

[edit] A sample of EE manifest

 
package = "lua"
version = "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"
}

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.
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: {"src/", "src/myfolder"}).
The openfile node is a project relative path to the file to open when the project creation is finish ( by default src/main.lua).