{"action":"created","comment":{"url":"https://api.github.com/repos/WebAssembly/design/pulls/comments/34940256","id":34940256,"diff_hunk":"@@ -0,0 +1,112 @@\n+# Modules\n+\n+The distributable, loadable, and executable unit of code in WebAssembly\n+is called a **module**. A module contains:\n+* a set of [imports and exports](Modules.md#imports-and-exports);\n+* a section defining the [initial state of linear memory](Modules.md#initial-state-of-linear-memory);\n+* a section containing [code](Modules.md#code-section);\n+* after the MVP, sections containing [debugging/symbol information](Tooling.md); and\n+* possibly other sections in the future.\n+\n+While WebAssembly modules are designed to interoperate with ES6 modules\n+in a Web environment (more details [below](Modules.md#integration-with-es6-modules)),\n+WebAssembly modules are defined independently of JavaScript and do not require\n+the host environment to include a JavaScript VM.\n+\n+## Imports and Exports\n+\n+A module defines a set of functions in its\n+[code section](Modules.md#code-section) and can declare and name a subset of\n+these functions to be **exports**. The meaning of exports (how and when they are\n+called) is defined by the host environment. For example, a minimal shell\n+environment might only probe for and call a `_start` export when given a module\n+to execute.\n+\n+A module can declare a set of **imports**. An import is a tuple containing a\n+module name, the name of an exported function to import from the named module,\n+and the signature to use for that import within the importing module. Within a\n+module, the import can be [directly called](AstSemantics.md#calls) like a\n+function (according to its locally-declared signature).\n+\n+The WebAssembly spec does not define how imports are interpreted:\n+* the host environment can interpret the module name as a file path, a URL,\n+  a key in a fixed set of builtin modules or the host environment may invoke a\n+  user-defined hook to resolve the module name to one of these;\n+* the module name does not need to resolve to a WebAssembly module; it\n+  could resolve to a builtin module (implemented by the host environment) or a\n+  module written in another, compatible language; and\n+* the meaning of calling an imported function is host-defined.\n+\n+The open-ended nature of module imports allow them to be used to expose\n+arbitrary host environment functionality to WebAssembly code, similar to a\n+native `syscall`. For example, a shell environment could define a builtin\n+`stdio` module with an export `puts`.\n+\n+In C/C++, an undefined `extern` declaration could be compiled to an import and\n+C/C++ calls to this `extern` would then be compiled to calls to this import. This\n+is one way low-level C/C++ libraries could call out of WebAssembly in order to\n+implement portable source-level interfaces (e.g., POSIX, OpenGL or SDL) in\n+terms of host-specific functionality.\n+\n+### Integration with ES6 modules\n+\n+While ES6 defines how to parse, link and execute a module, ES6 does not\n+define when this parsing/linking/execution occurs. An additional extension\n+to the HTML spec is required to say when a script is parsed as a module instead\n+of normal global code. This work is [ongoing](TODO). Currently, the following\n+entry points for modules are being considered:\n+* `<script type=\"module\">`;\n+* an overload to the `Worker` constructor;\n+* an overload to the `importScripts` Worker API;\n+\n+Additionally, an ES6 module can recursively import other modules via `import`\n+statements.\n+\n+For WebAssembly/ES6 module integration, the idea is that all the above module\n+entry points could also load WebAssembly modules simply by passing the URL of a\n+WebAssembly module. The distinction of whether the module was WebAssembly or ES6\n+code could be made by namespacing or by content sniffing the first bytes of the\n+fetched resource (which, for WebAssembly, would be a non-ASCII&mdash;and thus\n+illegal as JavaScript&mdash;[magic number](https://en.wikipedia.org/wiki/Magic_number_%28programming%29)).\n+Thus, the whole module-loading pipeline (resolving the name to a URL, fetching\n+the URL, any other [loader hooks](http://whatwg.github.io/loader/)) would be\n+shared and only the final stage would fork into either the JavaScript parser or\n+the WebAssembly decoder.\n+\n+Any non-builtin imports from within a WebAssembly module would be treated as\n+if they were `import` statements of an ES6 module. If an ES6 module `import`ed\n+a WebAssembly module, the WebAssembly module's exports would be linked as if\n+they were the exports of an ES6 module. Once parsing and linking phases\n+were complete, a WebAssembly module would have its `_start` function called in\n+place of executing the ES6 module top-level script.\n+\n+This integration strategy should allow WebAssembly modules to be fairly\n+interchangeable with ES6 modules (ignoring \n+[GC/Web API](FutureFeatures.md#gc/dom-integration) signature restrictions of the\n+WebAssembly MVP) and thus it should be natural to compose a single application\n+from both kinds of code. This goal motivates the \n+[semantic design](AstSemantics.md#linear-memory) of giving each WebAssembly\n+module its own disjoint linear memory. Otherwise, if all modules shared a single\n+linear memory (all modules with the same realm? origin? window?&mdash;even the\n+scope of \"all\" is a nuanced question), a single app using multiple\n+independent libraries would have to hope that all the WebAssembly modules\n+transitively used by those libraries \"played well\" together (e.g., explicitly\n+shared `malloc` and coordinated global address ranges). Instead, the\n+[dynamic linking future feature](FutureFeatures.md#dynamic-linking) is intended\n+to allow *explicitly* sharing linear memory between multiple modules.\n+\n+## Initial state of linear memory\n+\n+A module will contain a section declaring the heap size (initial and maximum","path":"Modules.md","position":100,"original_position":100,"commit_id":"863aa72ac1cc19590eb8a5c26a34026f5949f6ed","original_commit_id":"863aa72ac1cc19590eb8a5c26a34026f5949f6ed","user":{"login":"sunfishcode","id":4503403,"avatar_url":"https://avatars.githubusercontent.com/u/4503403?v=3","gravatar_id":"","url":"https://api.github.com/users/sunfishcode","html_url":"https://github.com/sunfishcode","followers_url":"https://api.github.com/users/sunfishcode/followers","following_url":"https://api.github.com/users/sunfishcode/following{/other_user}","gists_url":"https://api.github.com/users/sunfishcode/gists{/gist_id}","starred_url":"https://api.github.com/users/sunfishcode/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sunfishcode/subscriptions","organizations_url":"https://api.github.com/users/sunfishcode/orgs","repos_url":"https://api.github.com/users/sunfishcode/repos","events_url":"https://api.github.com/users/sunfishcode/events{/privacy}","received_events_url":"https://api.github.com/users/sunfishcode/received_events","type":"User","site_admin":false},"body":"Say \"linear memory\" instead of \"heap\", here and one spot below too.","created_at":"2015-07-17T23:47:41Z","updated_at":"2015-07-17T23:47:41Z","html_url":"https://github.com/WebAssembly/design/pull/270#discussion_r34940256","pull_request_url":"https://api.github.com/repos/WebAssembly/design/pulls/270","_links":{"self":{"href":"https://api.github.com/repos/WebAssembly/design/pulls/comments/34940256"},"html":{"href":"https://github.com/WebAssembly/design/pull/270#discussion_r34940256"},"pull_request":{"href":"https://api.github.com/repos/WebAssembly/design/pulls/270"}}},"pull_request":{"url":"https://api.github.com/repos/WebAssembly/design/pulls/270","id":40194603,"html_url":"https://github.com/WebAssembly/design/pull/270","diff_url":"https://github.com/WebAssembly/design/pull/270.diff","patch_url":"https://github.com/WebAssembly/design/pull/270.patch","issue_url":"https://api.github.com/repos/WebAssembly/design/issues/270","number":270,"state":"open","locked":false,"title":"Consolidate explanation of modules into a new Modules.md and improve explanation","user":{"login":"lukewagner","id":9660325,"avatar_url":"https://avatars.githubusercontent.com/u/9660325?v=3","gravatar_id":"","url":"https://api.github.com/users/lukewagner","html_url":"https://github.com/lukewagner","followers_url":"https://api.github.com/users/lukewagner/followers","following_url":"https://api.github.com/users/lukewagner/following{/other_user}","gists_url":"https://api.github.com/users/lukewagner/gists{/gist_id}","starred_url":"https://api.github.com/users/lukewagner/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/lukewagner/subscriptions","organizations_url":"https://api.github.com/users/lukewagner/orgs","repos_url":"https://api.github.com/users/lukewagner/repos","events_url":"https://api.github.com/users/lukewagner/events{/privacy}","received_events_url":"https://api.github.com/users/lukewagner/received_events","type":"User","site_admin":false},"body":"This PR is an attempt to consolidate the discussion of modules and their integration with ES6 modules into one place and also provide a better explanation.\r\n\r\nIndependently, there's been some agreement to work on a new \"level 0\" version of the [loader spec](http://whatwg.github.io/loader/) with the goal of being \"just enough to be able to ship ES6 modules and WebAssembly modules\".  When there is a URL to point to, I'll update the TODO link in Modules.md.\r\n\r\nEspecially interested for feedback from @ajklein.\r\n\r\n(On a side note, with this PR, MVP.md is now pretty empty and ad hoc, it'd be good to tidy it up.  I might do that if noone beats me to it.)","created_at":"2015-07-17T02:06:28Z","updated_at":"2015-07-17T23:47:41Z","closed_at":null,"merged_at":null,"merge_commit_sha":"bcb02823e49723122d9946ae3a92e2822975888d","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/WebAssembly/design/pulls/270/commits","review_comments_url":"https://api.github.com/repos/WebAssembly/design/pulls/270/comments","review_comment_url":"https://api.github.com/repos/WebAssembly/design/pulls/comments{/number}","comments_url":"https://api.github.com/repos/WebAssembly/design/issues/270/comments","statuses_url":"https://api.github.com/repos/WebAssembly/design/statuses/863aa72ac1cc19590eb8a5c26a34026f5949f6ed","head":{"label":"WebAssembly:better-explain-modules","ref":"better-explain-modules","sha":"863aa72ac1cc19590eb8a5c26a34026f5949f6ed","user":{"login":"WebAssembly","id":11578470,"avatar_url":"https://avatars.githubusercontent.com/u/11578470?v=3","gravatar_id":"","url":"https://api.github.com/users/WebAssembly","html_url":"https://github.com/WebAssembly","followers_url":"https://api.github.com/users/WebAssembly/followers","following_url":"https://api.github.com/users/WebAssembly/following{/other_user}","gists_url":"https://api.github.com/users/WebAssembly/gists{/gist_id}","starred_url":"https://api.github.com/users/WebAssembly/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/WebAssembly/subscriptions","organizations_url":"https://api.github.com/users/WebAssembly/orgs","repos_url":"https://api.github.com/users/WebAssembly/repos","events_url":"https://api.github.com/users/WebAssembly/events{/privacy}","received_events_url":"https://api.github.com/users/WebAssembly/received_events","type":"Organization","site_admin":false},"repo":{"id":34808241,"name":"design","full_name":"WebAssembly/design","owner":{"login":"WebAssembly","id":11578470,"avatar_url":"https://avatars.githubusercontent.com/u/11578470?v=3","gravatar_id":"","url":"https://api.github.com/users/WebAssembly","html_url":"https://github.com/WebAssembly","followers_url":"https://api.github.com/users/WebAssembly/followers","following_url":"https://api.github.com/users/WebAssembly/following{/other_user}","gists_url":"https://api.github.com/users/WebAssembly/gists{/gist_id}","starred_url":"https://api.github.com/users/WebAssembly/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/WebAssembly/subscriptions","organizations_url":"https://api.github.com/users/WebAssembly/orgs","repos_url":"https://api.github.com/users/WebAssembly/repos","events_url":"https://api.github.com/users/WebAssembly/events{/privacy}","received_events_url":"https://api.github.com/users/WebAssembly/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/WebAssembly/design","description":"WebAssembly Design Documents","fork":false,"url":"https://api.github.com/repos/WebAssembly/design","forks_url":"https://api.github.com/repos/WebAssembly/design/forks","keys_url":"https://api.github.com/repos/WebAssembly/design/keys{/key_id}","collaborators_url":"https://api.github.com/repos/WebAssembly/design/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/WebAssembly/design/teams","hooks_url":"https://api.github.com/repos/WebAssembly/design/hooks","issue_events_url":"https://api.github.com/repos/WebAssembly/design/issues/events{/number}","events_url":"https://api.github.com/repos/WebAssembly/design/events","assignees_url":"https://api.github.com/repos/WebAssembly/design/assignees{/user}","branches_url":"https://api.github.com/repos/WebAssembly/design/branches{/branch}","tags_url":"https://api.github.com/repos/WebAssembly/design/tags","blobs_url":"https://api.github.com/repos/WebAssembly/design/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/WebAssembly/design/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/WebAssembly/design/git/refs{/sha}","trees_url":"https://api.github.com/repos/WebAssembly/design/git/trees{/sha}","statuses_url":"https://api.github.com/repos/WebAssembly/design/statuses/{sha}","languages_url":"https://api.github.com/repos/WebAssembly/design/languages","stargazers_url":"https://api.github.com/repos/WebAssembly/design/stargazers","contributors_url":"https://api.github.com/repos/WebAssembly/design/contributors","subscribers_url":"https://api.github.com/repos/WebAssembly/design/subscribers","subscription_url":"https://api.github.com/repos/WebAssembly/design/subscription","commits_url":"https://api.github.com/repos/WebAssembly/design/commits{/sha}","git_commits_url":"https://api.github.com/repos/WebAssembly/design/git/commits{/sha}","comments_url":"https://api.github.com/repos/WebAssembly/design/comments{/number}","issue_comment_url":"https://api.github.com/repos/WebAssembly/design/issues/comments{/number}","contents_url":"https://api.github.com/repos/WebAssembly/design/contents/{+path}","compare_url":"https://api.github.com/repos/WebAssembly/design/compare/{base}...{head}","merges_url":"https://api.github.com/repos/WebAssembly/design/merges","archive_url":"https://api.github.com/repos/WebAssembly/design/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/WebAssembly/design/downloads","issues_url":"https://api.github.com/repos/WebAssembly/design/issues{/number}","pulls_url":"https://api.github.com/repos/WebAssembly/design/pulls{/number}","milestones_url":"https://api.github.com/repos/WebAssembly/design/milestones{/number}","notifications_url":"https://api.github.com/repos/WebAssembly/design/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/WebAssembly/design/labels{/name}","releases_url":"https://api.github.com/repos/WebAssembly/design/releases{/id}","created_at":"2015-04-29T17:36:05Z","updated_at":"2015-07-17T21:26:05Z","pushed_at":"2015-07-17T23:41:29Z","git_url":"git://github.com/WebAssembly/design.git","ssh_url":"git@github.com:WebAssembly/design.git","clone_url":"https://github.com/WebAssembly/design.git","svn_url":"https://github.com/WebAssembly/design","homepage":"","size":3040,"stargazers_count":4011,"watchers_count":4011,"language":null,"has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":201,"mirror_url":null,"open_issues_count":59,"forks":201,"open_issues":59,"watchers":4011,"default_branch":"master"}},"base":{"label":"WebAssembly:master","ref":"master","sha":"0d19a06e1e15803ebc729837703a364aea94992e","user":{"login":"WebAssembly","id":11578470,"avatar_url":"https://avatars.githubusercontent.com/u/11578470?v=3","gravatar_id":"","url":"https://api.github.com/users/WebAssembly","html_url":"https://github.com/WebAssembly","followers_url":"https://api.github.com/users/WebAssembly/followers","following_url":"https://api.github.com/users/WebAssembly/following{/other_user}","gists_url":"https://api.github.com/users/WebAssembly/gists{/gist_id}","starred_url":"https://api.github.com/users/WebAssembly/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/WebAssembly/subscriptions","organizations_url":"https://api.github.com/users/WebAssembly/orgs","repos_url":"https://api.github.com/users/WebAssembly/repos","events_url":"https://api.github.com/users/WebAssembly/events{/privacy}","received_events_url":"https://api.github.com/users/WebAssembly/received_events","type":"Organization","site_admin":false},"repo":{"id":34808241,"name":"design","full_name":"WebAssembly/design","owner":{"login":"WebAssembly","id":11578470,"avatar_url":"https://avatars.githubusercontent.com/u/11578470?v=3","gravatar_id":"","url":"https://api.github.com/users/WebAssembly","html_url":"https://github.com/WebAssembly","followers_url":"https://api.github.com/users/WebAssembly/followers","following_url":"https://api.github.com/users/WebAssembly/following{/other_user}","gists_url":"https://api.github.com/users/WebAssembly/gists{/gist_id}","starred_url":"https://api.github.com/users/WebAssembly/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/WebAssembly/subscriptions","organizations_url":"https://api.github.com/users/WebAssembly/orgs","repos_url":"https://api.github.com/users/WebAssembly/repos","events_url":"https://api.github.com/users/WebAssembly/events{/privacy}","received_events_url":"https://api.github.com/users/WebAssembly/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/WebAssembly/design","description":"WebAssembly Design Documents","fork":false,"url":"https://api.github.com/repos/WebAssembly/design","forks_url":"https://api.github.com/repos/WebAssembly/design/forks","keys_url":"https://api.github.com/repos/WebAssembly/design/keys{/key_id}","collaborators_url":"https://api.github.com/repos/WebAssembly/design/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/WebAssembly/design/teams","hooks_url":"https://api.github.com/repos/WebAssembly/design/hooks","issue_events_url":"https://api.github.com/repos/WebAssembly/design/issues/events{/number}","events_url":"https://api.github.com/repos/WebAssembly/design/events","assignees_url":"https://api.github.com/repos/WebAssembly/design/assignees{/user}","branches_url":"https://api.github.com/repos/WebAssembly/design/branches{/branch}","tags_url":"https://api.github.com/repos/WebAssembly/design/tags","blobs_url":"https://api.github.com/repos/WebAssembly/design/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/WebAssembly/design/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/WebAssembly/design/git/refs{/sha}","trees_url":"https://api.github.com/repos/WebAssembly/design/git/trees{/sha}","statuses_url":"https://api.github.com/repos/WebAssembly/design/statuses/{sha}","languages_url":"https://api.github.com/repos/WebAssembly/design/languages","stargazers_url":"https://api.github.com/repos/WebAssembly/design/stargazers","contributors_url":"https://api.github.com/repos/WebAssembly/design/contributors","subscribers_url":"https://api.github.com/repos/WebAssembly/design/subscribers","subscription_url":"https://api.github.com/repos/WebAssembly/design/subscription","commits_url":"https://api.github.com/repos/WebAssembly/design/commits{/sha}","git_commits_url":"https://api.github.com/repos/WebAssembly/design/git/commits{/sha}","comments_url":"https://api.github.com/repos/WebAssembly/design/comments{/number}","issue_comment_url":"https://api.github.com/repos/WebAssembly/design/issues/comments{/number}","contents_url":"https://api.github.com/repos/WebAssembly/design/contents/{+path}","compare_url":"https://api.github.com/repos/WebAssembly/design/compare/{base}...{head}","merges_url":"https://api.github.com/repos/WebAssembly/design/merges","archive_url":"https://api.github.com/repos/WebAssembly/design/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/WebAssembly/design/downloads","issues_url":"https://api.github.com/repos/WebAssembly/design/issues{/number}","pulls_url":"https://api.github.com/repos/WebAssembly/design/pulls{/number}","milestones_url":"https://api.github.com/repos/WebAssembly/design/milestones{/number}","notifications_url":"https://api.github.com/repos/WebAssembly/design/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/WebAssembly/design/labels{/name}","releases_url":"https://api.github.com/repos/WebAssembly/design/releases{/id}","created_at":"2015-04-29T17:36:05Z","updated_at":"2015-07-17T21:26:05Z","pushed_at":"2015-07-17T23:41:29Z","git_url":"git://github.com/WebAssembly/design.git","ssh_url":"git@github.com:WebAssembly/design.git","clone_url":"https://github.com/WebAssembly/design.git","svn_url":"https://github.com/WebAssembly/design","homepage":"","size":3040,"stargazers_count":4011,"watchers_count":4011,"language":null,"has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":201,"mirror_url":null,"open_issues_count":59,"forks":201,"open_issues":59,"watchers":4011,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/WebAssembly/design/pulls/270"},"html":{"href":"https://github.com/WebAssembly/design/pull/270"},"issue":{"href":"https://api.github.com/repos/WebAssembly/design/issues/270"},"comments":{"href":"https://api.github.com/repos/WebAssembly/design/issues/270/comments"},"review_comments":{"href":"https://api.github.com/repos/WebAssembly/design/pulls/270/comments"},"review_comment":{"href":"https://api.github.com/repos/WebAssembly/design/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/WebAssembly/design/pulls/270/commits"},"statuses":{"href":"https://api.github.com/repos/WebAssembly/design/statuses/863aa72ac1cc19590eb8a5c26a34026f5949f6ed"}}}}