SPeCS Research Group

User Tools

Site Tools

Trace:
doc:lara:tips

Warning: Undefined array key -1 in /home/feupptspecs/public_html/wiki/inc/html.php on line 1458

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
doc:lara:tips [2022/01/15 19:39]
jbispo 		doc:lara:tips [2022/01/15 20:20] (current)
jbispo
Line 1: Line 1:
 ====== LARA General Tips ====== ====== LARA General Tips ======
  
-The LARA language is JavaScript (plain JavaScript is valid LARA code) extended with custom syntax oriented for source code analysis and transformation.+===== Naming Conventions =====
  
-Recently LARA has been moving away from language-specific constructs (e.g., select, apply) in favor of JavaScript-based APIs (e.g., weaver.Query). +General Javascript styling guides apply, such as: 
-==== Aspects ====+  * Variable names and functions use camelCase with the first letter in lowercase 
 +  * Class names should be nouns, in use CamelCase with the first letter of each internal word capitalized 
 +  * Global variables use ALLCAPS 
 +  * Private functions/members start with underscore '_' (they will not appear in the generated documentation)
  
-Aspects are regions of code where LARA syntax can be used, and are similar to functions. They are also the entry point of a LARA script, the first aspect of the script is executed by default.+LARA-specific constructs have the following rules: 
 +  * Aspect names follow the same rules of Classes 
 +  * Join point attributes and actions follow the same rules as variable names and functions
  
-Aspectdef definition 
  
-<code lara> +/* Furthermore, since importing will evaluate all imported LARA and JS scripts in the same context, to help keep things organized, */
-// The main aspect is the first declared in the file +
-aspectdef MyFirstAspect +
-   // aspect code +
-end+
  
-aspectdef ASecondAspect // An aspect that can be called in the main aspect +We highly recommend that LARA/JS scripts declare a single global variable or class with the same name as the script (e.g., file Query.js/.lara declares a new class/aspect Query).
-   // aspect code +
-end +
-</code> +
- +
- +
- +
-==== Aspect Inputs and Outputs ==== +
- +
-Input parameter definition: +
- +
-<code lara> +
-input +
-    funcs, +
-    opt +
-end +
-</code> +
- +
-Input parameter definition with default values: +
- +
-<code lara> +
-input +
-    funcs = ['kernel'], +
-    opt = ['unroll', 'interchange', 'tile'] +
-end +
-</code> +
- +
-Output definition. Output cannot be initialized inside the **output** block: +
- +
-<code lara> +
-output +
-    optFuncs, +
-    code +
-end +
- +
-optFuncs = []; +
-code = ''; +
-</code> +
- +
-==== Calling Aspects ==== +
- +
-Simple aspect call: +
- +
-<code lara> +
-call OptimizeProgram(); +
-</code> +
- +
-Calling an aspect with arguments: +
- +
-<code lara> +
-call OptimizeFunctions(functions, optimizations); +
-</code> +
- +
-Calling an aspect with named arguments: +
- +
-<code lara> +
-call OptimizeFunctions(opt: optimizations, funcs: ['gridIterate']); +
-</code> +
- +
- +
-Calling an aspect and retrieving the outputs: +
- +
-<code lara> +
-// Current syntax +
-var optimizer = call OptimizeFunctions(functions, optimizations); +
- +
-// Previous syntax +
-call optimizer : OptimizeFunctions(functions, optimizations); +
- +
-var changedFuncs = optimizer.optFuncs; +
-var finalCode = optimizer.code; +
-</code> +
- +
-Assigning an aspect call to a variable for later use. Can still use input arguments and outputs as shown before: +
- +
-<code lara> +
-var optimizer = new OptimizeFunctions(functions, optimizations); +
- +
-call optimizer(); // or optimizer.call() +
- +
-var changedFuncs = optimizer.optFuncs; +
-var finalCode = optimizer.code; +
-</code> +
- +
-Aspects can also be called inside Javascript files (.js). You need to build the aspect object and reference the complete path, separated by dollar signs ($):  +
- +
-<code lara> +
-// Calling aspect MeasureEnergy from inside a .js file +
- +
-(new lara$profiling$Energy$EnergyTest()).call(); +
-</code> +
-==== Using LARA Actions ==== +
- +
-Actions are used inside apply statements. There are two default actions, **insert** and **def**. Then, it is possible to use weaver-specific actions, which are called with the **exec** keyword: +
- +
-<code lara> +
-select function{'kernel'} end +
-apply +
-    insert before '/* Creating a clone. */';  // add a comment before the function +
-    def name = 'original_kernel';  // redefine the name of the kernel function +
-    exec clone('cloned_kernel');  // use a MANET-specific action to create a 'kernel' clone named 'cloned_kernel' +
-end +
-</code> +
- +
-When calling an action we can specify any join point in the chain to be the action target: +
- +
-<code lara> +
-select function.loop end +
-apply +
-    $loop.exec tile(8); +
-    $function.insert before '/* This function was transformed. */'; +
-end +
-</code> +
- +
-It is possible to omit the target, the last join point in the chain is used: +
- +
-<code lara> +
-select function.loop end +
-apply +
-    exec unroll(2);  // performed on the same loop as below +
-    $loop.exec tile(8);  // performed on the same loop as above +
-end +
-</code> +
- +
- +
-If the action returns a result, we can use the following syntax: +
- +
-<code lara> +
-   var result = $jp.exec <action_name>; +
-</code> +
- +
-If 'result' is a variable that already exists, 'var' can be omitted: +
- +
-<code lara> +
-   result = $jp.exec <action_name>; +
-</code> +
- +
-The keyword '.exec' can be omitted if you prefix the name of the action with the target join point, and add parenthesis: +
- +
-<code lara> +
-  result = $jp.<action_name>(); +
-</code> +
- +
-==== Calling shell commands ==== +
- +
-You can invoke shell commands from LARA using the function cmd. The first argument is the command, and the second an array with the arguments for the command: +
- +
-<code lara> +
- +
-cmd("ls", ["-l", "-v"]); +
- +
-</code> +
- +
- +
-==== Using LARA from the Command Line ==== +
- +
-=== Include Folder === +
- +
-To add include folders, use the flag -i. To add more than one folder, use double quotes and separate the folders with the file separator character of your current system +
- +
-<code> +
- +
-larai -i "libs1;libs2" +
- +
-</code> +
- +
-=== Passing Arguments to the Aspect === +
- +
-To pass arguments to the top-level aspect use the flag -av. The input is a JSON representation of the input: +
- +
-<code> +
- +
-larai -av "{inputFile:'data.json',execute:true,iterations:10}" +
- +
-</code>  +
- +
- +
-==== Codedef Sections ==== +
- +
-To insert sections of code that span several lines, you can define codedef sections, which act as templates. Example: +
- +
-<code lara> +
- +
-codedef CodeTemplate(param1, param2) %{ +
-// This code is inserted as-is, without escaping +
- +
-// To apply the values of parameters, use [[]] +
-var [[param1]] = [[param2]]; +
- +
-}% end +
- +
-</code> +
- +
-Declared codedefs can then be used in the code as functions: +
- +
-<code lara> +
- +
-code = CodeTemplate("varName", 2); +
- +
-</code>+
  
-====== Miscellaneous ====== 
  
-==== Regular Expressions ====+===== Regular Expressions =====
  
 Lara supports JavaScript regular expressions, for instance: Lara supports JavaScript regular expressions, for instance:
Line 254: Line 54:
 </code> </code>
  
-==== Importing LARA Files ====+===== Importing LARA Files =====
  
 LARA supports importing LARA files (with extension .lara) that are present in the include path (flag -i) using the keyword **import**. To import a file, you have to use the path to the file from the include folder, using '.' as separator and omitting the extension of the file. For instance, if you add as include the folder ~/foo and you want to import the file ~/foo/bar/Aspect.lara, you can write the following code: LARA supports importing LARA files (with extension .lara) that are present in the include path (flag -i) using the keyword **import**. To import a file, you have to use the path to the file from the include folder, using '.' as separator and omitting the extension of the file. For instance, if you add as include the folder ~/foo and you want to import the file ~/foo/bar/Aspect.lara, you can write the following code:
Line 266: Line 66:
 Import statements must be the first statements in a LARA file. LARA weavers come bundled with support for a set of imports, which are part of their API (e.g., [[http://specs.fe.up.pt/tools/clava/doc/|Clava API]]). Import statements must be the first statements in a LARA file. LARA weavers come bundled with support for a set of imports, which are part of their API (e.g., [[http://specs.fe.up.pt/tools/clava/doc/|Clava API]]).
  
-==== Importing JS Files ====+===== Importing JS Files =====
  
-All JS files (with extension .js) that are present in folders of the include path are automatically evaluated before any LARA file. However, there is a mechanism for importing specific JS files at the same time as LARA files.  +JS files that are present in an include path can be imported using the LARA keyword **import**. The same rules of importing of LARA files apply. For instance, if you add as include the folder ~/src-js and you want to import the file ~/src-js/bar/Foo.js, you can write the following code:
- +
-When the name of a folder of the include path ends with '-lara', the JS files are not automatically loaded, but instead, must be imported using the keyword **import**. The same rules of importing of LARA files apply. For instance, if you add as include the folder ~/src-lara and you want to import the file ~/src-lara/bar/Foo.js, you can write the following code:+
  
 <code lara> <code lara>
Line 283: Line 81:
 Furthermore, since importing will evaluate all imported LARA and JS scripts in the same context, to help keep things organized, we recommend that LARA/JS scripts declare a single variable/class with the same name as the import (e.g., importing weaver.Query declares a new class Query). Furthermore, since importing will evaluate all imported LARA and JS scripts in the same context, to help keep things organized, we recommend that LARA/JS scripts declare a single variable/class with the same name as the import (e.g., importing weaver.Query declares a new class Query).
  
-Since LARA is based on an older version of JS (i.e. EcmaScript 5), many recent JavaScript features are not available in LARA code. We recommend using JS files in order to have access to more recent features of JavaScript. Currently the LARA framework supports EcmaScript 2021 for JS files. +Since LARA scripts are based on an older version of JS (i.e. EcmaScript 5), many recent JavaScript features are not available in LARA code. We recommend using JS files in order to have access to more recent features of JavaScript. 
-==== Reading/Writing JSON Files ====+ 
 +/* Currently the LARA framework supports EcmaScript 2021 for JS files. */ 
 +===== Reading/Writing JSON Files =====
  
 LARA supports reading from and writing to JSON objects with the object **Io**: LARA supports reading from and writing to JSON objects with the object **Io**:
Line 299: Line 99:
  
  
-==== Testing Join Point Types ====+===== Testing the type of a join point ===== 
 + 
 +All join points have the attribute ''.joinPointType'', which you might feel tempted to use to check the type of a join point, for further processing. However, it is highly preferable to use ''.instanceOf(<join_point_name>)'' instead.
  
-To test if a join point is of a certain type, use the attribute ''.instanceOf(<join_point_name>)''. This respects the join point hierarchy (e.g., "call" and "expr" can both return true) and is more robust than directly checking the name of the join point, i.e. ''$jp.joinPointType === <join_point_name>''.+This respects the join point hierarchy (e.g., "call" and "expr" can both return true) and is more robust than directly checking the name of the join point, i.e. ''$jp.joinPointType === "call"''.
doc/lara/tips.1642275555.txt.gz · Last modified: 2022/01/15 19:39 by jbispo

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki