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
(Created page with "In this tutorial, I will show how to create a simple EE. See also EE detailed documention. == What is an EE ? == <blockq...")
 
Line 17: Line 17:
 
Copy the content of the EE in the created project.
 
Copy the content of the EE in the created project.
  
−
2) Rockspec
+
== Step2: Rockspec file ==
 
Edit the .rockspec file
 
Edit the .rockspec file
 
Edit name and description as follow.
 
Edit name and description as follow.
−
<code>
+
<source lang="lua">
 
package = "lfslua"
 
package = "lfslua"
 
version = "5.1"
 
version = "5.1"
Line 36: Line 36:
 
   dir="docs"
 
   dir="docs"
 
}
 
}
−
</code>
+
</source>
  
−
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.
  
 +
<pre>
 
Declare the module
 
Declare the module
 
--- @module lfs
 
--- @module lfs
 +
</pre>
  
 
Let's comment a function. I will explain only mkdir, but it the same for each one.
 
Let's comment a function. I will explain only mkdir, but it the same for each one.
  
 
Here the definition of mkdir function from the LFS manual:
 
Here the definition of mkdir function from the LFS manual:
 +
<blockquote>
 
lfs.mkdir (dirname)
 
lfs.mkdir (dirname)
 
     Creates a new directory. The argument is the name of the new directory.
 
     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.  
+
     Returns true if the operation was successful; in case of error, it returns nil plus an error string.
 +
</blockquote>
  
 
Translate it in LDL. See LDL documentation.
 
Translate it in LDL. See LDL documentation.
 
Put the description first:
 
Put the description first:
 +
<pre>
 
--- Creates a new directory.
 
--- Creates a new directory.
 +
</pre>
  
 
Set the function name
 
Set the function name
 +
<pre>
 
-- @function [parent=#lfs]mkdir
 
-- @function [parent=#lfs]mkdir
 +
</pre>
  
 
Declare the parametter:
 
Declare the parametter:
 +
<pre>
 
-- @param #string dirname name of the new directory
 
-- @param #string dirname name of the new directory
 +
</pre>
  
 
Declare returns
 
Declare returns
 +
<pre>
 
-- @return true If the operation was successful
 
-- @return true If the operation was successful
 
-- @return nil, #string In case of error
 
-- @return nil, #string In case of error
 +
</pre>
  
 
Add following statement at the end of the file (Due to an LDT limitation, files have to contain valid lua to be takken in account)
 
Add following statement at the end of the file (Due to an LDT limitation, files have to contain valid lua to be takken in account)
 
return nil.
 
return nil.
  
−
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 load some module in global variable, you should declare them in the global.doclua file as follow:
 
---
 
---
Line 78: Line 90:
 
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 type in the lfs module.
  
−
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 main folder, using eclipse (Export project as archive) or an external tool.
 
Import the archive as a new EE.
 
Import the archive as a new EE.
Line 84: Line 96:
 
Test aucompletion after "lfs."
 
Test aucompletion after "lfs."
  
−
6) Advanced users: Use Lua documentor to generate the documentation.
+
== Going further ==
 +
 
 +
=== Step 6: Advanced users: Use Lua documentor to generate the documentation. ===
 
To be written
 
To be written
  
−
7) Advanced users: Add a default project template in your EE.
+
=== Step 7: Add a default project template in your EE. ===
 
To be written
 
To be written

Revision as of 03:46, 8 August 2014

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


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.

Tutorial Use Case

I have made a custom interpreter based on Lua 5.1 interpreter but I added the LuaFileSystem library in it. That means while using my interpreter I don't need anymore to install LFS using LuaRocks or require it as the module is preloaded in the global variable lfs.

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 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 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 LDL. See LDL documentation. 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 takken 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

Retrieved from "https://wiki.eclipse.org/index.php?title=LDT/User_Area/Tutorial/Create_a_simple_Execution_Environment&oldid=368696"

Back to the top