Add to FAQ: What is the function of the files named *.amd.json?

[hhzl]

For the answer add the link to the wiki entry here .....

[ghost]

Not good question. All other .amd.json files have exact same reason. They are all local.amd.jsons, just a bit misplaced.

Hannes Hirzel wrote:

For the answer add the link to the wiki entry here .....

—
Reply to this email directly or view it on GitHub
#46.

[hhzl]

Ok, local.amd.json describes the mapping for the project which is in the folder where the ``local.amd.jsons` resides, correct?

For example for the project snap.svg demo the local.amd.json file has

      {
          "paths": {
                        "amber-snapsvg": "src"
                       }
           }

and it refers to the Amber-snapsvg-demo. Other *.amd.json files which could be in the directory (in that particular project there are none) refer to libraries where a local.amd.json is missing, correct?

How should I restate the question?

[ghost]

Yes, that. What you did not mention are other possible local.amd.json files (in library directories, if they are .amd.json-aware). I don't know how to restate. Maybe it should actually be two questions, one for local.amd.json, one for dirname.amd.json, which is explained as "just the displaced local.amd.json for directory dirname".

Hannes Hirzel wrote:

Ok, |local.amd.json| describes the mapping for the project which is in
the folder where the `|local.amd.jsons| resides, correct?

For example for the project snap.svg demo
https://github.com/hhzl/Amber-snapsvg-demo the local.amd.json file has

| {
"paths": {
"amber-snapsvg": "src"
}
}
|

and it refers to the Amber-snapsvg-demo
https://github.com/hhzl/Amber-snapsvg-demo. Other |*.amd.json| files
which could be in the directory (in that particular project there are
none) refer to libraries where a |local.amd.json
| is missing, correct?

How should I restate the question?

—
Reply to this email directly or view it on GitHub
#46 (comment).

[hhzl]

What about this proposal for an answer: (and comment as well on the slightly changed question)

Answer

local.amd.json files refer to mappings of a project name to the source directory where the source files may be found.

Each project or library is supposed to have such a file. But not all libraries have one. Instead of adding a local.amd.json to the library which would touch that library folder a *.amd.json file named theLibraryDirectoryName.amd.json has to be added to the root folder of your project which uses that library. But the file content, i.e. the path mappings have still to be written in a way as if the file would reside in that library directory.

[ghost]

"local.amd.json files refer to mappings of a project name to the source directory where the source files may be found" is very narrow thus not really true. What do you mean by "project name"? What is "source directory"? If you try to apply these to the second part on dirname,amd.json, it fails miserably. You often do not map a path, but you map directly a module. So "project name" (even if you rename it to "namespace") has no analogy.

[ghost]

The thing is complicated by the fact that what you map is either planned to use as a path (namespace of amber project, for example), but sometimes it is used as a module itself (so it should refer to a file; in which case .js is added to it (but if you load it via 'css!' loader plugin, then .css is added)).

[ghost]

Not a hard thing once you read over the requirejs docs, but scary until that point.

[ghost]

And of course, *.amd.json does not contain only paths sections, it may contain any other piece of requirejs config, form which "shim" and "map" have also its uses sometimes.

[hhzl]

So we might refer to http://requirejs.org/docs/api.html for the full answer and give a narrower answer which does not cover all cases but some frequent ones people encounter.

This means a list of examples explained. Often it is easier to have a full list of explanations then a set of rules to understand an issue. For an implementor of course a spec has to be completly described with a set of rules.

[ghost]

Whatever works, I just don't want it to be misguiding. As I probably don't know how to present it to the users, I hope someone out there will be able to communicate it better.

[hhzl]

useful graphic and illustration

[hhzl]

New attempt at an answer:

*.amd.json files are consulted by the amber config command to construct config.js which is the as the main (generated) configuration file includes everything. Most often you do not need to call amber config as grunt devel does it.

Read more:

1. graphical overview
2. illustration
3. http://requirejs.org/docs/api.html

[ghost]

Not just grunt devel, grunt deploy as well. In fact, I would rather not even mention amber config, just name the functionality (like "*.amd.json files are consulted by AMD config builder task to construct ... AMD config building happens always when you issue grunt devel or grunt deploy").