Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "LDT/User Area/Tutorial/Create a simple Execution Environment"
Line 1: | Line 1: | ||
− | In this tutorial, I will show how to create a simple EE. See also [[LDT/User_Area/Execution_Environment_file_format|EE detailed | + | In this tutorial, I will show how to create a simple EE. See also [[LDT/User_Area/Execution_Environment_file_format|EE detailed documentation]]. |
== What is an EE ? == | == What is an EE ? == | ||
Line 7: | Line 7: | ||
Extract from [[LDT/User_Area/User_Guides/User_Guide_1.2#Execution_Environment| User Guide]]. | Extract from [[LDT/User_Area/User_Guides/User_Guide_1.2#Execution_Environment| User Guide]]. | ||
− | == | + | == Why this tutorial ? == |
− | + | Suppose that you have made a custom interpreter based on Lua 5.1 interpreter and you added the [http://keplerproject.github.io/luafilesystem/index.html LuaFileSystem] library in it. That means while using the interpreter there is no needs to install LFS using LuaRocks or require it as the module is preloaded in the global variable '''lfs'''. Then while codding on LDT, you don't have any user-assistance on the LFS library, this is because your EE doesn't contain a description of the LFS library. In the following steps you can learn how to create a simple EE to enable user assistance on the LFS library. | |
== Step1: Setup the project == | == Step1: Setup the project == | ||
Line 14: | Line 14: | ||
#Open LDT and create a project named "lualfs" without any EE. | #Open LDT and create a project named "lualfs" without any EE. | ||
#Rename the src folder into api. | #Rename the src folder into api. | ||
− | #Copy the content of the EE in the created project. | + | #Copy the content of the downloaded EE in the created project. |
== Step2: Rockspec file == | == Step2: Rockspec file == | ||
Line 54: | Line 54: | ||
</blockquote> | </blockquote> | ||
− | Translate it in | + | Translate it in [[LDT/User_Area/Documentation_Language|Documentation Language]]. |
Put the description first: | Put the description first: | ||
<pre> | <pre> |
Revision as of 05:41, 8 August 2014
In this tutorial, I will show how to create a simple EE. See also EE detailed documentation.
Contents
What is an EE ?
An Execution Environment, is a file containing information about the environment where a Lua application is supposed to be run. An environment is a set of libraries and global variables available to the application out of the box, as in Lua 5.1 or MOAI SDK. Only one Execution Environment is expected per project. The idea is to provide a file which describe elements of an environment. Provided information allows LDT to offer better code completion, code navigation and documentation layout.
Extract from User Guide.
Why this tutorial ?
Suppose that you have made a custom interpreter based on Lua 5.1 interpreter and you added the LuaFileSystem library in it. That means while using the interpreter there is no needs to install LFS using LuaRocks or require it as the module is preloaded in the global variable lfs. Then while codding on LDT, you don't have any user-assistance on the LFS library, this is because your EE doesn't contain a description of the LFS library. In the following steps you can learn how to create a simple EE to enable user assistance on the LFS library.
Step1: Setup the project
- Download the Lua-5.1 standard EE sources.
- Open LDT and create a project named "lualfs" without any EE.
- Rename the src folder into api.
- Copy the content of the downloaded EE in the created project.
Step2: Rockspec file
Edit the .rockspec file Edit name and description as follow.
package = "lfslua" version = "5.1" flags = { ee = true } description = { summary = "Lua 5.1 with LFS Execution Environment", detailed = [[Lua 5.1 with LFS Execution Environment Support]], licence = "EPL-MIT", homepage= "http://eclipse.org/ldt" } api = { file = "api.zip" } documentation = { dir="docs" }
Step 3: Write your module doclua
Create a new doclua file in the api folder.
Declare the module --- @module lfs
Let's comment a function. I will explain only mkdir, but it's the same for each one.
Here the definition of mkdir function from the LFS manual:
lfs.mkdir (dirname)
- Creates a new directory. The argument is the name of the new directory.
- Returns true if the operation was successful; in case of error, it returns nil plus an error string.
Translate it in Documentation Language. Put the description first:
--- Creates a new directory.
Set the function name
-- @function [parent=#lfs]mkdir
Declare the parametter:
-- @param #string dirname name of the new directory
Declare returns
-- @return true If the operation was successful -- @return nil, #string In case of error
Add following statement at the end of the file (Due to an LDT limitation, files have to contain valid Lua to be taken in account) return nil.
Step 4: Declare global variable
If your interpreter load some module in global variable, you should declare them in the global.doclua file as follow:
--- -- This library provides generic functions for file manipulation. -- This is a global variable which hold the preloaded @{lfs} module. -- @field[parent = #global] lfs#lfs lfs preloaded module
- The parent = #global indicate that we are declaring a global var./
- The lfs#lfs is a external reference to the lfs type in the lfs module.
Step 5: Zip and test
- Zip the main folder, using eclipse (Export project as archive) or an external tool.
- Import the archive as a new EE.
- Create a new project with this new EE.
- Test aucompletion after "lfs."
Going further
Step 6: Advanced users: Use Lua documentor to generate the documentation.
To be written
Step 7: Add a default project template in your EE.
To be written