Skip to main content

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.

Jump to: navigation, search

Difference between revisions of "LDT/User Area/Tutorial/Create a simple Execution Environment"

< LDT
 
(8 intermediate revisions by one other user not shown)
Line 10: Line 10:
 
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.
 
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 ==
+
If you have just put a library like LFS in the path, with LuaRocks for exemple, you just need to put a '''.doclua''' file representing the LFS library in your project buildpath. See the third step to see how to write the '''.luadoc''' file.
#Download the Lua-5.1 standard EE sources.
+
 
#Open LDT and create a project named "lualfs" without any EE.
+
== Step1: Get the source ==
#Rename the src folder into api.
+
#Get the Lua-5.1 standard EE sources. Actually, there is no easy way to get it, but here two methods:
#Copy the content of the downloaded EE in the created project.
+
#*Clone the [https://git.eclipse.org/c/ldt/org.eclipse.ldt.git/ git repository] and copy the folder ''org.eclipse.ldt/plugins/org.eclipse.ldt.support.lua51/src-ee/lua-5.1''
 +
#*Find the local path by expending a Lua51 Execution Environment in a LDT project and copy the folder '''lua-5.1''':
 +
<center>[[File:EEPath.jpg]]</center>
 +
#Rename the folder '''lua-5.1''' into '''lualfs'''
 +
#Extract the '''lualfs/api.zip''' archive into an '''lualfs/api''' folder.
  
 
== Step2: Rockspec file ==
 
== Step2: Rockspec file ==
Edit the .rockspec file
+
Edit '''name''' and '''description''' as follow.
Edit name and description as follow.
+
 
<source lang="lua">
 
<source lang="lua">
 
package = "lfslua"
 
package = "lfslua"
 
version = "5.1"
 
version = "5.1"
 +
grammar = "lua-5.1"
 
flags = { ee = true }
 
flags = { ee = true }
 
description = {
 
description = {
Line 36: Line 40:
 
}
 
}
 
</source>
 
</source>
 +
 +
You can find more about the rockspec file, in the [[LDT/User_Area/Execution_Environment_file_format|related documentation]].
  
 
== Step 3: Write your module doclua ==
 
== Step 3: Write your module doclua ==
Create a new doclua file in the api folder.
+
Create a new '''doclua''' file in the api folder. You can edit it in the '''LDT''' to have syntax coloring and code completion.
  
 
<pre>
 
<pre>
Line 45: Line 51:
 
</pre>
 
</pre>
  
Let's comment a function. I will explain only '''mkdir''', but it's the same for each one.
+
Let's comment a function. Here the explanation for '''mkdir''', but it's the same for each functions.
  
 
Here the definition of mkdir function from the LFS manual:
 
Here the definition of mkdir function from the LFS manual:
Line 65: Line 71:
 
</pre>
 
</pre>
  
Declare the parametter:
+
Declare the parameter:
 
<pre>
 
<pre>
 
-- @param #string dirname name of the new directory
 
-- @param #string dirname name of the new directory
Line 76: Line 82:
 
</pre>
 
</pre>
  
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)
+
Add following statement at the end of the file (Due to an LDT limitation, files have to contain valid Lua statement to be taken in account)
 +
<pre>
 
return nil.
 
return nil.
 +
</pre>
  
 
== Step 4: Declare global variable ==
 
== 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:
+
If your interpreter preload some module in some '''global variable''', you should declare them in the global.doclua file as follow:
 
<pre>
 
<pre>
 
---
 
---
Line 88: Line 96:
 
</pre>
 
</pre>
  
*The ''parent = #global'' indicate that we are declaring a global var./
+
*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.
+
*The ''lfs#lfs'' is a external reference to the ''lfs'' module.
  
 
== Step 5: Zip and test ==
 
== Step 5: Zip and test ==
# Zip the main folder, using eclipse (Export project as archive) or an external tool.
+
# Zip the lualfs/api folder into lualfs/api.zip.
 +
# Zip the lualfs folder.
 
# Import the archive as a new EE.
 
# Import the archive as a new EE.
 
# Create a new project with this new EE.
 
# Create a new project with this new EE.
# Test aucompletion after "lfs."
+
# Test the auto-completion after ''lfs.''
  
 
== Going further ==
 
== Going further ==
Line 104: Line 113:
 
=== Step 7:  Add a default project template in your EE. ===
 
=== Step 7:  Add a default project template in your EE. ===
 
To be written
 
To be written
 +
 +
== Questions ==
 +
If you have some questions or commentaries, please respond this topic on the [https://www.eclipse.org/forums/index.php/m/1697588/#msg_1697588 forum].

Latest revision as of 05:38, 5 June 2015

In this tutorial, I will show how to create a simple EE. See also EE detailed documentation.

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.

If you have just put a library like LFS in the path, with LuaRocks for exemple, you just need to put a .doclua file representing the LFS library in your project buildpath. See the third step to see how to write the .luadoc file.

Step1: Get the source

  1. Get the Lua-5.1 standard EE sources. Actually, there is no easy way to get it, but here two methods:
    • Clone the git repository and copy the folder org.eclipse.ldt/plugins/org.eclipse.ldt.support.lua51/src-ee/lua-5.1
    • Find the local path by expending a Lua51 Execution Environment in a LDT project and copy the folder lua-5.1:
EEPath.jpg
  1. Rename the folder lua-5.1 into lualfs
  2. Extract the lualfs/api.zip archive into an lualfs/api folder.

Step2: Rockspec file

Edit name and description as follow.

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

You can find more about the rockspec file, in the related documentation.

Step 3: Write your module doclua

Create a new doclua file in the api folder. You can edit it in the LDT to have syntax coloring and code completion.

Declare the module
--- @module lfs

Let's comment a function. Here the explanation for mkdir, but it's the same for each functions.

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 parameter:

-- @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 statement to be taken in account)

return nil.

Step 4: Declare global variable

If your interpreter preload some module in some 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 module.

Step 5: Zip and test

  1. Zip the lualfs/api folder into lualfs/api.zip.
  2. Zip the lualfs folder.
  3. Import the archive as a new EE.
  4. Create a new project with this new EE.
  5. Test the auto-completion 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

Questions

If you have some questions or commentaries, please respond this topic on the forum.

Back to the top