Opened 9 years ago

Last modified 9 years ago

#11919 closed enhancement

AMD transform build tool limitations — at Version 12

Reported by: ben hockey Owned by: Rawld Gill
Priority: high Milestone: 1.7
Component: BuildTools Version: 1.5
Keywords: Cc: Rawld Gill, Kris Zyp
Blocked By: Blocking:

Description (last modified by Rawld Gill)

The build system now contains transforms that take modules written in the AMD format back to the v1.5 module format. These transforms are intended as a temporary, short-term hack for early adopters of the AMD module format. Aside from ensuring that the transforms work with released dojo code, no guarantees are made re these transforms.

With this understanding, this ticket tracks capabilities and problems with these transforms.

Change History (12)

comment:1 Changed 9 years ago by ben hockey

in addition, it seems that you cannot have a return value that has a number in it's name. for example:

define("dojox/math/random/prng4", ["dojo"], function (dojo) {
    var prng4 = ... // define the module

    return prng4;
});

comment:2 Changed 9 years ago by ben hockey

(In [23098]) allow a number to be used in the identifier of the value returned by a module. refs #11919

comment:3 Changed 9 years ago by ben hockey

Description: modified (diff)
Summary: fileUtil.transformAsyncModule does not transform anonymous module definitionsAMD transform build tool problems

i updated the title to be more general - there are a few small things which shouldn't need individual tickets.

comment:4 Changed 9 years ago by ben hockey

returning a function call doesn't work:

define("dojox/math/_base", ["dojo"], function (dojo) {
	var m = dojo.getObject("dojox.math", true);
	
	return dojo.mixin(m, {
            // the stuff to mixin to dojox.math
        });
});

most of the problems in this ticket have simple work arounds but i'm just trying to capture them all in one place for reference.

comment:5 Changed 9 years ago by ben hockey

multiple return points must be avoided

define("dojox/math/round", ["dojo"], function (dojo) {
	var dm = dojo.getObject("dojox.math");

	var round = dm.round = function(...){
	    // ...
	}

	if((0.9).toFixed() == 0){
		return dm.round = function(v, p, m){
			var d = Math.pow(10, -p || 0), a = Math.abs(v);
			if(!v || a >= d || a * Math.pow(10, p + 1) < 5){
				d = 0;
			}
			return round(v, p, m) + (v > 0 ? d : -d);
		};
	}
	return round;
});

comment:6 Changed 9 years ago by Rawld Gill

Owner: changed from James Burke to Rawld Gill

comment:7 Changed 9 years ago by Rawld Gill

Status: newassigned

comment:8 Changed 9 years ago by Rawld Gill

(In [23124]) enhanced inverse AMD transform in build util, refs #11919

comment:9 Changed 9 years ago by Rawld Gill

Rules for writing AMD modules for consumption by the temporary inverse AMD transform in the v1.x build system (as of [23124])

First, remember that you have the existing build system capabilities available and you can use build pragmas to include/exclude chunks of code. For example,

//>>includeStart("AMD", kwArgs.AMD);
return function() {
  // stuff
};
//>>includeEnd("AMD");

will effectively exclude the delimited code unless the build flag AMD is set, and this flag is not set in normal builds.

Normal Code Modules

For AMD modules either include the pragma

// AMD-ID "<module-id>"

Or begin the file with *exactly*

define(

The AMD-ID pragma can appear anywhere, the word "AMD-ID" is case-insensitive, white space is optional elsewhere on the line. The <module-id> must be in the AMD module identifier format (i.e., my/stuff, not my.stuff).

In either case, the file is expected to contain exactly one AMD module definition. The module identifier for the AMD definition may be either given explicitly in the define call or by the AMD-ID pragma. The AMD-ID pragma allows you to define an anonymous module (i.e., a module without an ID). If you give both, the AMD-ID pragma will be ignored.

Here are a couple of examples:

define("my/module", ["your/module"], function(yours) {
  x= getObject("module", true, "my");

  x.myAPI= function() { 
    // stuff
  );

  return x.myAPI;
});

And...

// AMD-ID "my/module"
define(["your/module"], function(yours) {
  x= getObject("module", true, "my");

  x.myAPI= function() { 
    // stuff
  );
});

Both result in the following transform:

dojo.provide("my.module");
dojo.require("your.module");
  x= getObject("module", true, "my");

  x.myAPI= function() { 
    // stuff
  )

Returns From AMD Modules

Typically, AMD modules return a value and this return value must be discarded for use with the v1.x build system. The transform can automatically detect and remove returns from the AMD factory if either of the following conditions are met:

  • (1) the return value is a JavaScript dotted name (e.g., myApi, myModule.myApi, etc.), (2) the return statement is immediately followed by an optional comment and/or optional white space, and (3) the file ends with precisely /\}\);\s*/. For example,
return dojo.back; // commentary
});

...or...

  • The return statement is followed on the same line with the pragma // AMD-return . For example,
  return my.awesome.api; // AMD-return

If the AMD-return pragma is used, it must be on the same line; other commentary may follow the word "AMD-return".

Notice, in particular, that more-complex returns, e.g., returning functions, are not supported. As mentioned above, you can handle such general cases by protecting the return expression with a build pragma that will strip the return during a normal build. For example,

//>>includeStart("AMD", kwArgs.AMD);
return function() {
  // stuff
};
//>>includeEnd("AMD");

I18N Bundles

For i18n bundles, surround the part of the file you want to go through to the v1.x builder with the lines:

//begin v1.x content

and

//end v1.x content

The transform will pass anything between the two delimiters given above on to the build system. Multiple blocks are *not* supported. Though the main purpose of this this transform is help with i18n bundles, it is not limited to this use. You may find it useful in any resource that causes problems using other techniques to keep two implementations in one file.

comment:10 in reply to:  4 Changed 9 years ago by Rawld Gill

Replying to neonstalwart:

returning a function call doesn't work:

[snip]

You can get this to work by using standard build pragmas. See my extended explanation above.

comment:11 in reply to:  5 Changed 9 years ago by Rawld Gill

Replying to neonstalwart:

multiple return points must be avoided

[snip]

This has been addressed in [23124]; see extended explanation above.

comment:12 Changed 9 years ago by Rawld Gill

Description: modified (diff)
Summary: AMD transform build tool problemsAMD transform build tool limitations
Note: See TracTickets for help on using tickets.