From 76e2228c25b2b5a2911e97116d0558918772ded4 Mon Sep 17 00:00:00 2001 From: Charlie Birks Date: Thu, 19 Jun 2014 11:41:15 +0100 Subject: [PATCH 01/60] Support webkit gamepad api --- src/library_html5.js | 43 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 34 insertions(+), 9 deletions(-) diff --git a/src/library_html5.js b/src/library_html5.js index d5d0cd6637a9c..a091b81fe4b94 100644 --- a/src/library_html5.js +++ b/src/library_html5.js @@ -765,10 +765,18 @@ var LibraryJSEvents = { {{{ makeSetValue('eventStruct+i*8', C_STRUCTS.EmscriptenGamepadEvent.axis, 'e.axes[i]', 'double') }}}; } for(var i = 0; i < e.buttons.length; ++i) { - {{{ makeSetValue('eventStruct+i*8', C_STRUCTS.EmscriptenGamepadEvent.analogButton, 'e.buttons[i].value', 'double') }}}; + if (typeof(e.buttons[i]) === 'object') { + {{{ makeSetValue('eventStruct+i*8', C_STRUCTS.EmscriptenGamepadEvent.analogButton, 'e.buttons[i].value', 'double') }}}; + } else { + {{{ makeSetValue('eventStruct+i*8', C_STRUCTS.EmscriptenGamepadEvent.analogButton, 'e.buttons[i]', 'double') }}}; + } } for(var i = 0; i < e.buttons.length; ++i) { - {{{ makeSetValue('eventStruct+i*4', C_STRUCTS.EmscriptenGamepadEvent.digitalButton, 'e.buttons[i].pressed', 'i32') }}}; + if (typeof(e.buttons[i]) === 'object') { + {{{ makeSetValue('eventStruct+i*4', C_STRUCTS.EmscriptenGamepadEvent.digitalButton, 'e.buttons[i].pressed', 'i32') }}}; + } else { + {{{ makeSetValue('eventStruct+i*4', C_STRUCTS.EmscriptenGamepadEvent.digitalButton, 'e.buttons[i] == 1.0', 'i32') }}}; + } } {{{ makeSetValue('eventStruct', C_STRUCTS.EmscriptenGamepadEvent.connected, 'e.connected', 'i32') }}}; {{{ makeSetValue('eventStruct', C_STRUCTS.EmscriptenGamepadEvent.index, 'e.index', 'i32') }}}; @@ -1248,26 +1256,43 @@ var LibraryJSEvents = { }, emscripten_set_gamepadconnected_callback: function(userData, useCapture, callbackfunc) { - if (!navigator.getGamepads) return {{{ cDefine('EMSCRIPTEN_RESULT_NOT_SUPPORTED') }}}; + if (!navigator.getGamepads && !navigator.webkitGetGamepads) return {{{ cDefine('EMSCRIPTEN_RESULT_NOT_SUPPORTED') }}}; JSEvents.registerGamepadEventCallback(window, userData, useCapture, callbackfunc, {{{ cDefine('EMSCRIPTEN_EVENT_GAMEPADCONNECTED') }}}, "gamepadconnected"); return {{{ cDefine('EMSCRIPTEN_RESULT_SUCCESS') }}}; }, emscripten_set_gamepaddisconnected_callback: function(userData, useCapture, callbackfunc) { - if (!navigator.getGamepads) return {{{ cDefine('EMSCRIPTEN_RESULT_NOT_SUPPORTED') }}}; + if (!navigator.getGamepads && !navigator.webkitGetGamepads) return {{{ cDefine('EMSCRIPTEN_RESULT_NOT_SUPPORTED') }}}; JSEvents.registerGamepadEventCallback(window, userData, useCapture, callbackfunc, {{{ cDefine('EMSCRIPTEN_EVENT_GAMEPADDISCONNECTED') }}}, "gamepaddisconnected"); return {{{ cDefine('EMSCRIPTEN_RESULT_SUCCESS') }}}; }, emscripten_get_num_gamepads: function() { - if (!navigator.getGamepads) return {{{ cDefine('EMSCRIPTEN_RESULT_NOT_SUPPORTED') }}}; - return navigator.getGamepads().length; + if (!navigator.getGamepads && !navigator.webkitGetGamepads) return {{{ cDefine('EMSCRIPTEN_RESULT_NOT_SUPPORTED') }}}; + if (navigator.getGamepads) { + return navigator.getGamepads().length; + } else if (navigator.webkitGetGamepads) { + var gamepads = navigator.webkitGetGamepads(); + + for (var i = 0; i < gamepads.length; i++) { + if (typeof gamepads[i] === 'undefined') { + return i; + } + } + + return gamepads.length; + } }, emscripten_get_gamepad_status: function(index, gamepadState) { - if (!navigator.getGamepads) return {{{ cDefine('EMSCRIPTEN_RESULT_NOT_SUPPORTED') }}}; - var gamepads = navigator.getGamepads(); - if (index < 0 || index >= gamepads.length) { + if (!navigator.getGamepads && !navigator.webkitGetGamepads) return {{{ cDefine('EMSCRIPTEN_RESULT_NOT_SUPPORTED') }}}; + var gamepads; + if (navigator.getGamepads) { + gamepads = navigator.getGamepads(); + } else if (navigator.webkitGetGamepads) { + gamepads = navigator.webkitGetGamepads(); + } + if (index < 0 || index >= gamepads.length || typeof gamepads[index] === 'undefined') { return {{{ cDefine('EMSCRIPTEN_RESULT_INVALID_PARAM') }}}; } JSEvents.fillGamepadEventData(gamepadState, gamepads[index]); From 948fae299a031d8a0e373bc9c526a46667ec2951 Mon Sep 17 00:00:00 2001 From: Charlie Birks Date: Mon, 30 Jun 2014 17:27:27 +0100 Subject: [PATCH 02/60] Review changes --- src/library_html5.js | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/src/library_html5.js b/src/library_html5.js index a091b81fe4b94..fdc11ec4ba4c4 100644 --- a/src/library_html5.js +++ b/src/library_html5.js @@ -1272,15 +1272,7 @@ var LibraryJSEvents = { if (navigator.getGamepads) { return navigator.getGamepads().length; } else if (navigator.webkitGetGamepads) { - var gamepads = navigator.webkitGetGamepads(); - - for (var i = 0; i < gamepads.length; i++) { - if (typeof gamepads[i] === 'undefined') { - return i; - } - } - - return gamepads.length; + return navigator.webkitGetGamepads().length; } }, @@ -1292,9 +1284,12 @@ var LibraryJSEvents = { } else if (navigator.webkitGetGamepads) { gamepads = navigator.webkitGetGamepads(); } - if (index < 0 || index >= gamepads.length || typeof gamepads[index] === 'undefined') { + if (index < 0 || index >= gamepads.length) { return {{{ cDefine('EMSCRIPTEN_RESULT_INVALID_PARAM') }}}; } + if (typeof gamepads[index] === 'undefined') { + return {{{ cDefine('EMSCRIPTEN_RESULT_NO_DATA') }}}; + } JSEvents.fillGamepadEventData(gamepadState, gamepads[index]); return {{{ cDefine('EMSCRIPTEN_RESULT_SUCCESS') }}}; }, From 627141c776b58b9bba82000d0bf10fde7571af97 Mon Sep 17 00:00:00 2001 From: Ningxin Hu Date: Mon, 18 Aug 2014 14:55:24 -0700 Subject: [PATCH 03/60] Update the simd.js It is based on version https://github.com/johnmccutchan/ecmascript_simd/blob/14aa231d3c1021695ecee467ef35e5d61c8c669e/src/ecmascript_simd.js Changes: 46620fd Add type check into SIMD operations. 1f29859 Fix float64x2.clamp implementation and add test case for it. 22b8ccf Use object properties instead of typed array as storage in polyfill 8941215 Changed conversion operators from SIMD.XXX.toYYY() to SIMD.YYY.fromXXX(), added 'select' operator for all types, added/updated tests 3eaaf69 Added reciprocal, reciprocalSqrt, shuffle, shuffleMix, comparison, and select operators to SIMD.float64x2 6f68238 Added SIMD.float64x2 (abs, neg, add, sub, mul, div, clamp, min, max, scale, sqrt, withX, withY, SIMD.float32x4.toFloat64x2) --- src/simd.js | 809 ++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 715 insertions(+), 94 deletions(-) diff --git a/src/simd.js b/src/simd.js index d5ff8b156b4be..1269cbdd4e27f 100644 --- a/src/simd.js +++ b/src/simd.js @@ -25,6 +25,48 @@ // SIMD module. var SIMD = {}; +// private stuff. +var _PRIVATE = {} + +_PRIVATE._f32 = new Float32Array(1); +_PRIVATE._i32 = new Int32Array(1); + +_PRIVATE._f32x4 = new Float32Array(4); +_PRIVATE._f64x2 = new Float64Array(_PRIVATE._f32x4.buffer); +_PRIVATE._i32x4 = new Int32Array(_PRIVATE._f32x4.buffer); + +_PRIVATE._f32x8 = new Float32Array(8); +_PRIVATE._f64x4 = new Float64Array(4); +_PRIVATE._i32x8 = new Int32Array(8); + +_PRIVATE.truncatef32 = function(x) { + _PRIVATE._f32[0] = x; + return _PRIVATE._f32[0]; +} + +_PRIVATE.truncatei32 = function(x) { + _PRIVATE._i32[0] = x; + return _PRIVATE._i32[0]; +} + +function checkFloat32x4(t) { + if (!(t instanceof SIMD.float32x4)) { + throw new TypeError("argument is not a float32x4."); + } +} + +function checkFloat64x2(t) { + if (!(t instanceof SIMD.float64x2)) { + throw new TypeError("argument is not a float64x2."); + } +} + +function checkInt32x4(t) { + if (!(t instanceof SIMD.int32x4)) { + throw new TypeError("argument is not a int32x4."); + } +} + /** * Construct a new instance of float32x4 number. * @param {double} value used for x lane. @@ -37,11 +79,10 @@ SIMD.float32x4 = function(x, y, z, w) { if (!(this instanceof SIMD.float32x4)) { return new SIMD.float32x4(x, y, z, w); } - this.storage_ = new Float32Array(4); - this.storage_[0] = x; - this.storage_[1] = y; - this.storage_[2] = z; - this.storage_[3] = w; + this.x_ = _PRIVATE.truncatef32(x); + this.y_ = _PRIVATE.truncatef32(y); + this.z_ = _PRIVATE.truncatef32(z); + this.w_ = _PRIVATE.truncatef32(w); } /** @@ -62,6 +103,141 @@ SIMD.float32x4.splat = function(s) { return SIMD.float32x4(s, s, s, s); } +/** + * @param {float64x2} t An instance of float64x2. + * @return {float32x4} A float32x4 with .x and .y from t + */ +SIMD.float32x4.fromFloat64x2 = function(t) { + checkFloat64x2(t); + var a = SIMD.float32x4.zero(); + a.x_ = t.x_; + a.y_ = t.y_; + return a; +} + +/** + * @param {int32x4} t An instance of int32x4. + * @return {float32x4} A float to integer conversion copy of t. + */ +SIMD.float32x4.fromInt32x4 = function(t) { + checkInt32x4(t); + var a = SIMD.float32x4.zero(); + a.x_ = t.x_; + a.y_ = t.y_; + a.z_ = t.z_; + a.w_ = t.w_; + return a; +} + +/** + * @param {float64x2} t An instance of float64x2. + * @return {float32x4} a bit-wise copy of t as a float32x4. + */ +SIMD.float32x4.fromFloat64x2Bits = function(t) { + checkFloat64x2(t); + _PRIVATE._f64x2[0] = t.x_; + _PRIVATE._f64x2[1] = t.y_; + return SIMD.float32x4(_PRIVATE._f32x4[0], + _PRIVATE._f32x4[1], + _PRIVATE._f32x4[2], + _PRIVATE._f32x4[3]); +} + +/** + * @param {int32x4} t An instance of int32x4. + * @return {float32x4} a bit-wise copy of t as a float32x4. + */ +SIMD.float32x4.fromInt32x4Bits = function(t) { + checkInt32x4(t); + _PRIVATE._i32x4[0] = t.x_; + _PRIVATE._i32x4[1] = t.y_; + _PRIVATE._i32x4[2] = t.z_; + _PRIVATE._i32x4[3] = t.w_; + return SIMD.float32x4(_PRIVATE._f32x4[0], + _PRIVATE._f32x4[1], + _PRIVATE._f32x4[2], + _PRIVATE._f32x4[3]); +} + +/** + * Construct a new instance of float64x2 number. + * @param {double} value used for x lane. + * @param {double} value used for y lane. + * @constructor + */ +SIMD.float64x2 = function(x, y) { + if (!(this instanceof SIMD.float64x2)) { + return new SIMD.float64x2(x, y); + } + this.x_ = x; + this.y_ = y; +} + +/** + * Construct a new instance of float64x2 number with 0.0 in all lanes. + * @constructor + */ +SIMD.float64x2.zero = function() { + return SIMD.float64x2(0.0, 0.0); +} + +/** + * Construct a new instance of float64x2 number with the same value + * in all lanes. + * @param {double} value used for all lanes. + * @constructor + */ +SIMD.float64x2.splat = function(s) { + return SIMD.float32x4(s, s); +} + +/** + * @param {float32x4} t An instance of float32x4. + * @return {float64x2} A float64x2 with .x and .y from t + */ +SIMD.float64x2.fromFloat32x4 = function(t) { + checkFloat32x4(t); + var a = SIMD.float64x2(t.x_, t.y_); + return a; +} + +/** + * @param {int32x4} t An instance of int32x4. + * @return {float64x2} A float64x2 with .x and .y from t + */ +SIMD.float64x2.fromInt32x4 = function(t) { + checkInt32x4(t); + var a = SIMD.float64x2.zero(); + a.x_ = t.x_; + a.y_ = t.y_; + return a; +} + +/** + * @param {float32x4} t An instance of float32x4. + * @return {float64x2} a bit-wise copy of t as a float64x2. + */ +SIMD.float64x2.fromFloat32x4Bits = function(t) { + checkFloat32x4(t); + _PRIVATE._f32x4[0] = t.x_; + _PRIVATE._f32x4[1] = t.y_; + _PRIVATE._f32x4[2] = t.z_; + _PRIVATE._f32x4[3] = t.w_; + return SIMD.float64x2(_PRIVATE._f64x2[0], _PRIVATE._f64x2[1]); +} + +/** + * @param {int32x4} t An instance of int32x4. + * @return {float64x2} a bit-wise copy of t as a float64x2. + */ +SIMD.float64x2.fromInt32x4Bits = function(t) { + checkInt32x4(t); + _PRIVATE._i32x4[0] = t.x_; + _PRIVATE._i32x4[1] = t.y_; + _PRIVATE._i32x4[2] = t.z_; + _PRIVATE._i32x4[3] = t.w_; + return SIMD.float64x2(_PRIVATE._f64x2[0], _PRIVATE._f64x2[1]); +} /** * Construct a new instance of int32x4 number. @@ -75,11 +251,10 @@ SIMD.int32x4 = function(x, y, z, w) { if (!(this instanceof SIMD.int32x4)) { return new SIMD.int32x4(x, y, z, w); } - this.storage_ = new Int32Array(4); - this.storage_[0] = x; - this.storage_[1] = y; - this.storage_[2] = z; - this.storage_[3] = w; + this.x_ = _PRIVATE.truncatei32(x); + this.y_ = _PRIVATE.truncatei32(y); + this.z_ = _PRIVATE.truncatei32(z); + this.w_ = _PRIVATE.truncatei32(w); } /** @@ -116,11 +291,62 @@ SIMD.int32x4.splat = function(s) { return SIMD.int32x4(s, s, s, s); } +/** + * @param {float32x4} t An instance of float32x4. + * @return {int32x4} with a integer to float conversion of t. + */ +SIMD.int32x4.fromFloat32x4 = function(t) { + checkFloat32x4(t); + var a = SIMD.int32x4(Math.floor(t.x_), Math.floor(t.y_), + Math.floor(t.z_), Math.floor(t.w_)); + return a; +} + +/** + * @param {float64x2} t An instance of float64x2. + * @return {int32x4} An int32x4 with .x and .y from t + */ +SIMD.int32x4.fromFloat64x2 = function(t) { + checkFloat64x2(t); + var a = SIMD.int32x4.zero(); + a.x_ = Math.floor(t.x_); + a.y_ = Math.floor(t.y_); + return a; +} + +/** + * @param {float32x4} t An instance of float32x4. + * @return {int32x4} a bit-wise copy of t as a int32x4. + */ +SIMD.int32x4.fromFloat32x4Bits = function(t) { + checkFloat32x4(t); + _PRIVATE._f32x4[0] = t.x_; + _PRIVATE._f32x4[1] = t.y_; + _PRIVATE._f32x4[2] = t.z_; + _PRIVATE._f32x4[3] = t.w_; + var alias = _PRIVATE._i32x4; + return SIMD.int32x4(alias[0], alias[1], alias[2], alias[3]); +} + +/** + * @param {float64x2} t An instance of float64x2. + * @return {int32x4} a bit-wise copy of t as an int32x4. + */ +SIMD.int32x4.fromFloat64x2Bits = function(t) { + checkFloat64x2(t); + _PRIVATE._f64x2[0] = t.x_; + _PRIVATE._f64x2[1] = t.y_; + var alias = _PRIVATE._i32x4; + var ix4 = SIMD.int32x4(alias[0], alias[1], alias[2], alias[3]); + return ix4; +} + /** * @return {float32x4} New instance of float32x4 with absolute values of * t. */ SIMD.float32x4.abs = function(t) { + checkFloat32x4(t); return SIMD.float32x4(Math.abs(t.x), Math.abs(t.y), Math.abs(t.z), Math.abs(t.w)); } @@ -130,6 +356,7 @@ SIMD.float32x4.abs = function(t) { * t. */ SIMD.float32x4.neg = function(t) { + checkFloat32x4(t); return SIMD.float32x4(-t.x, -t.y, -t.z, -t.w); } @@ -137,6 +364,8 @@ SIMD.float32x4.neg = function(t) { * @return {float32x4} New instance of float32x4 with a + b. */ SIMD.float32x4.add = function(a, b) { + checkFloat32x4(a); + checkFloat32x4(b); return SIMD.float32x4(a.x + b.x, a.y + b.y, a.z + b.z, a.w + b.w); } @@ -144,6 +373,8 @@ SIMD.float32x4.add = function(a, b) { * @return {float32x4} New instance of float32x4 with a - b. */ SIMD.float32x4.sub = function(a, b) { + checkFloat32x4(a); + checkFloat32x4(b); return SIMD.float32x4(a.x - b.x, a.y - b.y, a.z - b.z, a.w - b.w); } @@ -151,6 +382,8 @@ SIMD.float32x4.sub = function(a, b) { * @return {float32x4} New instance of float32x4 with a * b. */ SIMD.float32x4.mul = function(a, b) { + checkFloat32x4(a); + checkFloat32x4(b); return SIMD.float32x4(a.x * b.x, a.y * b.y, a.z * b.z, a.w * b.w); } @@ -158,6 +391,8 @@ SIMD.float32x4.mul = function(a, b) { * @return {float32x4} New instance of float32x4 with a / b. */ SIMD.float32x4.div = function(a, b) { + checkFloat32x4(a); + checkFloat32x4(b); return SIMD.float32x4(a.x / b.x, a.y / b.y, a.z / b.z, a.w / b.w); } @@ -166,6 +401,7 @@ SIMD.float32x4.div = function(a, b) { * between lowerLimit and upperLimit. */ SIMD.float32x4.clamp = function(t, lowerLimit, upperLimit) { + checkFloat32x4(t); var cx = t.x < lowerLimit.x ? lowerLimit.x : t.x; var cy = t.y < lowerLimit.y ? lowerLimit.y : t.y; var cz = t.z < lowerLimit.z ? lowerLimit.z : t.z; @@ -182,6 +418,7 @@ SIMD.float32x4.clamp = function(t, lowerLimit, upperLimit) { * t and other. */ SIMD.float32x4.min = function(t, other) { + checkFloat32x4(t); var cx = t.x > other.x ? other.x : t.x; var cy = t.y > other.y ? other.y : t.y; var cz = t.z > other.z ? other.z : t.z; @@ -194,6 +431,7 @@ SIMD.float32x4.min = function(t, other) { * t and other. */ SIMD.float32x4.max = function(t, other) { + checkFloat32x4(t); var cx = t.x < other.x ? other.x : t.x; var cy = t.y < other.y ? other.y : t.y; var cz = t.z < other.z ? other.z : t.z; @@ -206,6 +444,7 @@ SIMD.float32x4.max = function(t, other) { * t. */ SIMD.float32x4.reciprocal = function(t) { + checkFloat32x4(t); return SIMD.float32x4(1.0 / t.x, 1.0 / t.y, 1.0 / t.z, 1.0 / t.w); } @@ -214,14 +453,17 @@ SIMD.float32x4.reciprocal = function(t) { * reciprocal value of t. */ SIMD.float32x4.reciprocalSqrt = function(t) { + checkFloat32x4(t); return SIMD.float32x4(Math.sqrt(1.0 / t.x), Math.sqrt(1.0 / t.y), Math.sqrt(1.0 / t.z), Math.sqrt(1.0 / t.w)); } + /** * @return {float32x4} New instance of float32x4 with values of t * scaled by s. */ SIMD.float32x4.scale = function(t, s) { + checkFloat32x4(t); return SIMD.float32x4(s * t.x, s * t.y, s * t.z, s * t.w); } @@ -230,6 +472,7 @@ SIMD.float32x4.scale = function(t, s) { * values of t. */ SIMD.float32x4.sqrt = function(t) { + checkFloat32x4(t); return SIMD.float32x4(Math.sqrt(t.x), Math.sqrt(t.y), Math.sqrt(t.z), Math.sqrt(t.w)); } @@ -240,12 +483,17 @@ SIMD.float32x4.sqrt = function(t) { * @return {float32x4} New instance of float32x4 with lanes shuffled. */ SIMD.float32x4.shuffle = function(t, mask) { + checkFloat32x4(t); var _x = (mask) & 0x3; var _y = (mask >> 2) & 0x3; var _z = (mask >> 4) & 0x3; var _w = (mask >> 6) & 0x3; - return SIMD.float32x4(t.storage_[_x], t.storage_[_y], t.storage_[_z], - t.storage_[_w]); + _PRIVATE._f32x4[0] = t.x_; + _PRIVATE._f32x4[1] = t.y_; + _PRIVATE._f32x4[2] = t.z_; + _PRIVATE._f32x4[3] = t.w_; + var storage = _PRIVATE._f32x4; + return SIMD.float32x4(storage[_x], storage[_y], storage[_z], storage[_w]); } /** @@ -255,12 +503,23 @@ SIMD.float32x4.shuffle = function(t, mask) { * @return {float32x4} New instance of float32x4 with lanes shuffled. */ SIMD.float32x4.shuffleMix = function(t1, t2, mask) { + checkFloat32x4(t1); + checkFloat32x4(t2); var _x = (mask) & 0x3; var _y = (mask >> 2) & 0x3; var _z = (mask >> 4) & 0x3; var _w = (mask >> 6) & 0x3; - return SIMD.float32x4(t1.storage_[_x], t1.storage_[_y], t2.storage_[_z], - t2.storage_[_w]); + var storage = _PRIVATE._f32x8; + storage[0] = t1.x_; + storage[1] = t1.y_; + storage[2] = t1.z_; + storage[3] = t1.w_; + storage[4] = t2.x_; + storage[5] = t2.y_; + storage[6] = t2.z_; + storage[7] = t2.w_; + return SIMD.float32x4(storage[0 + _x], storage[0 + _y], + storage[4 + _z], storage[4 + _w]); } /** @@ -269,6 +528,7 @@ SIMD.float32x4.shuffleMix = function(t1, t2, mask) { * x replaced with {x}. */ SIMD.float32x4.withX = function(t, x) { + checkFloat32x4(t); return SIMD.float32x4(x, t.y, t.z, t.w); } @@ -278,6 +538,7 @@ SIMD.float32x4.withX = function(t, x) { * y replaced with {y}. */ SIMD.float32x4.withY = function(t, y) { + checkFloat32x4(t); return SIMD.float32x4(t.x, y, t.z, t.w); } @@ -287,6 +548,7 @@ SIMD.float32x4.withY = function(t, y) { * z replaced with {z}. */ SIMD.float32x4.withZ = function(t, z) { + checkFloat32x4(t); return SIMD.float32x4(t.x, t.y, z, t.w); } @@ -296,6 +558,7 @@ SIMD.float32x4.withZ = function(t, z) { * w replaced with {w}. */ SIMD.float32x4.withW = function(t, w) { + checkFloat32x4(t); return SIMD.float32x4(t.x, t.y, t.z, w); } @@ -306,6 +569,8 @@ SIMD.float32x4.withW = function(t, w) { * the result of t < other. */ SIMD.float32x4.lessThan = function(t, other) { + checkFloat32x4(t); + checkFloat32x4(other); var cx = t.x < other.x; var cy = t.y < other.y; var cz = t.z < other.z; @@ -320,6 +585,8 @@ SIMD.float32x4.lessThan = function(t, other) { * the result of t <= other. */ SIMD.float32x4.lessThanOrEqual = function(t, other) { + checkFloat32x4(t); + checkFloat32x4(other); var cx = t.x <= other.x; var cy = t.y <= other.y; var cz = t.z <= other.z; @@ -334,6 +601,8 @@ SIMD.float32x4.lessThanOrEqual = function(t, other) { * the result of t == other. */ SIMD.float32x4.equal = function(t, other) { + checkFloat32x4(t); + checkFloat32x4(other); var cx = t.x == other.x; var cy = t.y == other.y; var cz = t.z == other.z; @@ -348,6 +617,8 @@ SIMD.float32x4.equal = function(t, other) { * the result of t != other. */ SIMD.float32x4.notEqual = function(t, other) { + checkFloat32x4(t); + checkFloat32x4(other); var cx = t.x != other.x; var cy = t.y != other.y; var cz = t.z != other.z; @@ -362,6 +633,8 @@ SIMD.float32x4.notEqual = function(t, other) { * the result of t >= other. */ SIMD.float32x4.greaterThanOrEqual = function(t, other) { + checkFloat32x4(t); + checkFloat32x4(other); var cx = t.x >= other.x; var cy = t.y >= other.y; var cz = t.z >= other.z; @@ -376,6 +649,8 @@ SIMD.float32x4.greaterThanOrEqual = function(t, other) { * the result of t > other. */ SIMD.float32x4.greaterThan = function(t, other) { + checkFloat32x4(t); + checkFloat32x4(other); var cx = t.x > other.x; var cy = t.y > other.y; var cz = t.z > other.z; @@ -384,22 +659,23 @@ SIMD.float32x4.greaterThan = function(t, other) { } /** - * @param {float32x4} t An instance of float32x4. - * @return {int32x4} a bit-wise copy of t as a int32x4. + * @param {int32x4} t Selector mask. An instance of int32x4 + * @param {float32x4} trueValue Pick lane from here if corresponding + * selector lane is 0xFFFFFFFF + * @param {float32x4} falseValue Pick lane from here if corresponding + * selector lane is 0x0 + * @return {float32x4} Mix of lanes from trueValue or falseValue as + * indicated */ -SIMD.float32x4.bitsToInt32x4 = function(t) { - var alias = new Int32Array(t.storage_.buffer); - return SIMD.int32x4(alias[0], alias[1], alias[2], alias[3]); -} - -/** - * @param {float32x4} t An instance of float32x4. - * @return {int32x4} with a integer to float conversion of t. - */ -SIMD.float32x4.toInt32x4 = function(t) { - var a = SIMD.int32x4(t.storage_[0], t.storage_[1], t.storage_[2], - t.storage_[3]); - return a; +SIMD.float32x4.select = function(t, trueValue, falseValue) { + checkInt32x4(t); + checkFloat32x4(trueValue); + checkFloat32x4(falseValue); + var tv = SIMD.int32x4.fromFloat32x4Bits(trueValue); + var fv = SIMD.int32x4.fromFloat32x4Bits(falseValue); + var tr = SIMD.int32x4.and(t, tv); + var fr = SIMD.int32x4.and(SIMD.int32x4.not(t), fv); + return SIMD.float32x4.fromInt32x4Bits(SIMD.int32x4.or(tr, fr)); } /** @@ -408,9 +684,11 @@ SIMD.float32x4.toInt32x4 = function(t) { * @return {float32x4} New instance of float32x4 with values of a & b. */ SIMD.float32x4.and = function(a, b) { - var aInt = SIMD.float32x4.bitsToInt32x4(a); - var bInt = SIMD.float32x4.bitsToInt32x4(b); - return SIMD.int32x4.bitsToFloat32x4(SIMD.int32x4.and(aInt, bInt)); + checkFloat32x4(a); + checkFloat32x4(b); + var aInt = SIMD.int32x4.fromFloat32x4Bits(a); + var bInt = SIMD.int32x4.fromFloat32x4Bits(b); + return SIMD.float32x4.fromInt32x4Bits(SIMD.int32x4.and(aInt, bInt)); } /** @@ -419,9 +697,11 @@ SIMD.float32x4.and = function(a, b) { * @return {float32x4} New instance of float32x4 with values of a | b. */ SIMD.float32x4.or = function(a, b) { - var aInt = SIMD.float32x4.bitsToInt32x4(a); - var bInt = SIMD.float32x4.bitsToInt32x4(b); - return SIMD.int32x4.bitsToFloat32x4(SIMD.int32x4.or(aInt, bInt)); + checkFloat32x4(a); + checkFloat32x4(b); + var aInt = SIMD.int32x4.fromFloat32x4Bits(a); + var bInt = SIMD.int32x4.fromFloat32x4Bits(b); + return SIMD.float32x4.fromInt32x4Bits(SIMD.int32x4.or(aInt, bInt)); } /** @@ -430,9 +710,11 @@ SIMD.float32x4.or = function(a, b) { * @return {float32x4} New instance of float32x4 with values of a ^ b. */ SIMD.float32x4.xor = function(a, b) { - var aInt = SIMD.float32x4.bitsToInt32x4(a); - var bInt = SIMD.float32x4.bitsToInt32x4(b); - return SIMD.int32x4.bitsToFloat32x4(SIMD.int32x4.xor(aInt, bInt)); + checkFloat32x4(a); + checkFloat32x4(b); + var aInt = SIMD.int32x4.fromFloat32x4Bits(a); + var bInt = SIMD.int32x4.fromFloat32x4Bits(b); + return SIMD.float32x4.fromInt32x4Bits(SIMD.int32x4.xor(aInt, bInt)); } /** @@ -440,8 +722,294 @@ SIMD.float32x4.xor = function(a, b) { * @return {float32x4} New instance of float32x4 with values of ~a. */ SIMD.float32x4.not = function(a) { - var aInt = SIMD.float32x4.bitsToInt32x4(a); - return SIMD.int32x4.bitsToFloat32x4(SIMD.int32x4.not(aInt)); + checkFloat32x4(a); + var aInt = SIMD.int32x4.fromFloat32x4Bits(a); + return SIMD.float32x4.fromInt32x4Bits(SIMD.int32x4.not(aInt)); +} + +/** +* @return {float64x2} New instance of float64x2 with absolute values of +* t. +*/ +SIMD.float64x2.abs = function(t) { + checkFloat64x2(t); + return SIMD.float64x2(Math.abs(t.x), Math.abs(t.y)); +} + +/** + * @return {float64x2} New instance of float64x2 with negated values of + * t. + */ +SIMD.float64x2.neg = function(t) { + checkFloat64x2(t); + return SIMD.float64x2(-t.x, -t.y); +} + +/** + * @return {float64x2} New instance of float64x2 with a + b. + */ +SIMD.float64x2.add = function(a, b) { + checkFloat64x2(a); + checkFloat64x2(b); + return SIMD.float64x2(a.x + b.x, a.y + b.y); +} + +/** + * @return {float64x2} New instance of float64x2 with a - b. + */ +SIMD.float64x2.sub = function(a, b) { + checkFloat64x2(a); + checkFloat64x2(b); + return SIMD.float64x2(a.x - b.x, a.y - b.y); +} + +/** + * @return {float64x2} New instance of float64x2 with a * b. + */ +SIMD.float64x2.mul = function(a, b) { + checkFloat64x2(a); + checkFloat64x2(b); + return SIMD.float64x2(a.x * b.x, a.y * b.y); +} + +/** + * @return {float64x2} New instance of float64x2 with a / b. + */ +SIMD.float64x2.div = function(a, b) { + checkFloat64x2(a); + checkFloat64x2(b); + return SIMD.float64x2(a.x / b.x, a.y / b.y); +} + +/** + * @return {float64x2} New instance of float64x2 with t's values clamped + * between lowerLimit and upperLimit. + */ +SIMD.float64x2.clamp = function(t, lowerLimit, upperLimit) { + checkFloat64x2(t); + var cx = t.x < lowerLimit.x ? lowerLimit.x : t.x; + var cy = t.y < lowerLimit.y ? lowerLimit.y : t.y; + cx = cx > upperLimit.x ? upperLimit.x : cx; + cy = cy > upperLimit.y ? upperLimit.y : cy; + return SIMD.float64x2(cx, cy); +} + +/** + * @return {float64x2} New instance of float64x2 with the minimum value of + * t and other. + */ +SIMD.float64x2.min = function(t, other) { + checkFloat64x2(t); + checkFloat64x2(other); + var cx = t.x > other.x ? other.x : t.x; + var cy = t.y > other.y ? other.y : t.y; + return SIMD.float64x2(cx, cy); +} + +/** + * @return {float64x2} New instance of float64x2 with the maximum value of + * t and other. + */ +SIMD.float64x2.max = function(t, other) { + checkFloat64x2(t); + checkFloat64x2(other); + var cx = t.x < other.x ? other.x : t.x; + var cy = t.y < other.y ? other.y : t.y; + return SIMD.float64x2(cx, cy); +} + +/** + * @return {float64x2} New instance of float64x2 with reciprocal value of + * t. + */ +SIMD.float64x2.reciprocal = function(t) { + checkFloat64x2(t); + return SIMD.float64x2(1.0 / t.x, 1.0 / t.y); +} + +/** + * @return {float64x2} New instance of float64x2 with square root of the + * reciprocal value of t. + */ +SIMD.float64x2.reciprocalSqrt = function(t) { + checkFloat64x2(t); + return SIMD.float64x2(Math.sqrt(1.0 / t.x), Math.sqrt(1.0 / t.y)); +} + +/** + * @return {float64x2} New instance of float32x4 with values of t + * scaled by s. + */ +SIMD.float64x2.scale = function(t, s) { + checkFloat64x2(t); + return SIMD.float64x2(s * t.x, s * t.y); +} + +/** + * @return {float64x2} New instance of float32x4 with square root of + * values of t. + */ +SIMD.float64x2.sqrt = function(t) { + checkFloat64x2(t); + return SIMD.float64x2(Math.sqrt(t.x), Math.sqrt(t.y)); +} + +/** + * @param {float64x2} t An instance of float64x2 to be shuffled. + * @param {integer} mask One of the 4 shuffle masks, for example, SIMD.XY. + * @return {float64x2} New instance of float64x2 with lanes shuffled. + */ +SIMD.float64x2.shuffle = function(t, mask) { + checkFloat64x2(t); + var _x = (mask) & 0x1; + var _y = (mask >> 1) & 0x1; + var storage = _PRIVATE._f64x2; + storage[0] = t.x_; + storage[1] = t.y_; + return SIMD.float64x2(storage[_x], storage[_y]); +} + +/** + * @param {float64x2} t1 An instance of float64x2 to be shuffled. X lane in result + * @param {float64x2} t2 An instance of float64x2 to be shuffled. Y lane in result + * @param {integer} mask One of the 4 shuffle masks, for example, SIMD.XY. + * @return {float64x2} New instance of float64x2 with lanes shuffled. + */ +SIMD.float64x2.shuffleMix = function(t1, t2, mask) { + checkFloat64x2(t1); + checkFloat64x2(t2); + var _x = (mask) & 0x1; + var _y = (mask >> 1) & 0x1; + var storage = _PRIVATE._f64x4; + storage[0] = t1.x_; + storage[1] = t1.y_; + storage[2] = t2.x_; + storage[3] = t2.y_; + return SIMD.float64x2(storage[0 + _x], storage[2 + _y]); +} + +/** + * @param {double} value used for x lane. + * @return {float64x2} New instance of float64x2 with the values in t and + * x replaced with {x}. + */ +SIMD.float64x2.withX = function(t, x) { + checkFloat64x2(t); + return SIMD.float64x2(x, t.y); +} + +/** + * @param {double} value used for y lane. + * @return {float64x2} New instance of float64x2 with the values in t and + * y replaced with {y}. + */ +SIMD.float64x2.withY = function(t, y) { + checkFloat64x2(t); + return SIMD.float64x2(t.x, y); +} + +/** + * @param {float64x2} t An instance of float64x2. + * @param {float64x2} other An instance of float64x2. + * @return {int32x4} 0xFFFFFFFF or 0x0 in each lane depending on + * the result of t < other. + */ +SIMD.float64x2.lessThan = function(t, other) { + checkFloat64x2(t); + checkFloat64x2(other); + var cx = t.x < other.x; + var cy = t.y < other.y; + return SIMD.int32x4.bool(cx, cx, cy, cy); +} + +/** + * @param {float64x2} t An instance of float64x2. + * @param {float64x2} other An instance of float64x2. + * @return {int32x4} 0xFFFFFFFF or 0x0 in each lane depending on + * the result of t <= other. + */ +SIMD.float64x2.lessThanOrEqual = function(t, other) { + checkFloat64x2(t); + checkFloat64x2(other); + var cx = t.x <= other.x; + var cy = t.y <= other.y; + return SIMD.int32x4.bool(cx, cx, cy, cy); +} + +/** + * @param {float64x2} t An instance of float64x2. + * @param {float64x2} other An instance of float64x2. + * @return {int32x4} 0xFFFFFFFF or 0x0 in each lane depending on + * the result of t == other. + */ +SIMD.float64x2.equal = function(t, other) { + checkFloat64x2(t); + checkFloat64x2(other); + var cx = t.x == other.x; + var cy = t.y == other.y; + return SIMD.int32x4.bool(cx, cx, cy, cy); +} + +/** + * @param {float64x2} t An instance of float64x2. + * @param {float64x2} other An instance of float64x2. + * @return {int32x4} 0xFFFFFFFF or 0x0 in each lane depending on + * the result of t != other. + */ +SIMD.float64x2.notEqual = function(t, other) { + checkFloat64x2(t); + checkFloat64x2(other); + var cx = t.x != other.x; + var cy = t.y != other.y; + return SIMD.int32x4.bool(cx, cx, cy, cy); +} + +/** + * @param {float64x2} t An instance of float64x2. + * @param {float64x2} other An instance of float64x2. + * @return {int32x4} 0xFFFFFFFF or 0x0 in each lane depending on + * the result of t >= other. + */ +SIMD.float64x2.greaterThanOrEqual = function(t, other) { + checkFloat64x2(t); + checkFloat64x2(other); + var cx = t.x >= other.x; + var cy = t.y >= other.y; + return SIMD.int32x4.bool(cx, cx, cy, cy); +} + +/** + * @param {float64x2} t An instance of float64x2. + * @param {float64x2} other An instance of float64x2. + * @return {int32x4} 0xFFFFFFFF or 0x0 in each lane depending on + * the result of t > other. + */ +SIMD.float64x2.greaterThan = function(t, other) { + checkFloat64x2(t); + checkFloat64x2(other); + var cx = t.x > other.x; + var cy = t.y > other.y; + return SIMD.int32x4.bool(cx, cx, cy, cy); +} + +/** + * @param {int32x4} t Selector mask. An instance of int32x4 + * @param {float64x2} trueValue Pick lane from here if corresponding + * selector lanes are 0xFFFFFFFF + * @param {float64x2} falseValue Pick lane from here if corresponding + * selector lanes are 0x0 + * @return {float64x2} Mix of lanes from trueValue or falseValue as + * indicated + */ +SIMD.float64x2.select = function(t, trueValue, falseValue) { + checkInt32x4(t); + checkFloat64x2(trueValue); + checkFloat64x2(falseValue); + var tv = SIMD.int32x4.fromFloat64x2Bits(trueValue); + var fv = SIMD.int32x4.fromFloat64x2Bits(falseValue); + var tr = SIMD.int32x4.and(t, tv); + var fr = SIMD.int32x4.and(SIMD.int32x4.not(t), fv); + return SIMD.float64x2.fromInt32x4Bits(SIMD.int32x4.or(tr, fr)); } /** @@ -450,6 +1018,8 @@ SIMD.float32x4.not = function(a) { * @return {int32x4} New instance of int32x4 with values of a & b. */ SIMD.int32x4.and = function(a, b) { + checkInt32x4(a); + checkInt32x4(b); return SIMD.int32x4(a.x & b.x, a.y & b.y, a.z & b.z, a.w & b.w); } @@ -459,6 +1029,8 @@ SIMD.int32x4.and = function(a, b) { * @return {int32x4} New instance of int32x4 with values of a | b. */ SIMD.int32x4.or = function(a, b) { + checkInt32x4(a); + checkInt32x4(b); return SIMD.int32x4(a.x | b.x, a.y | b.y, a.z | b.z, a.w | b.w); } @@ -468,6 +1040,8 @@ SIMD.int32x4.or = function(a, b) { * @return {int32x4} New instance of int32x4 with values of a ^ b. */ SIMD.int32x4.xor = function(a, b) { + checkInt32x4(a); + checkInt32x4(b); return SIMD.int32x4(a.x ^ b.x, a.y ^ b.y, a.z ^ b.z, a.w ^ b.w); } @@ -476,6 +1050,7 @@ SIMD.int32x4.xor = function(a, b) { * @return {int32x4} New instance of int32x4 with values of ~t */ SIMD.int32x4.not = function(t) { + checkInt32x4(t); return SIMD.int32x4(~t.x, ~t.y, ~t.z, ~t.w); } @@ -484,6 +1059,7 @@ SIMD.int32x4.not = function(t) { * @return {int32x4} New instance of int32x4 with values of -t */ SIMD.int32x4.neg = function(t) { + checkInt32x4(t); return SIMD.int32x4(-t.x, -t.y, -t.z, -t.w); } @@ -493,6 +1069,8 @@ SIMD.int32x4.neg = function(t) { * @return {int32x4} New instance of int32x4 with values of a + b. */ SIMD.int32x4.add = function(a, b) { + checkInt32x4(a); + checkInt32x4(b); return SIMD.int32x4(a.x + b.x, a.y + b.y, a.z + b.z, a.w + b.w); } @@ -502,6 +1080,8 @@ SIMD.int32x4.add = function(a, b) { * @return {int32x4} New instance of int32x4 with values of a - b. */ SIMD.int32x4.sub = function(a, b) { + checkInt32x4(a); + checkInt32x4(b); return SIMD.int32x4(a.x - b.x, a.y - b.y, a.z - b.z, a.w - b.w); } @@ -511,6 +1091,8 @@ SIMD.int32x4.sub = function(a, b) { * @return {int32x4} New instance of int32x4 with values of a * b. */ SIMD.int32x4.mul = function(a, b) { + checkInt32x4(a); + checkInt32x4(b); return SIMD.int32x4(Math.imul(a.x, b.x), Math.imul(a.y, b.y), Math.imul(a.z, b.z), Math.imul(a.w, b.w)); } @@ -521,12 +1103,17 @@ SIMD.int32x4.mul = function(a, b) { * @return {int32x4} New instance of float32x4 with lanes shuffled. */ SIMD.int32x4.shuffle = function(t, mask) { + checkInt32x4(t); var _x = (mask) & 0x3; var _y = (mask >> 2) & 0x3; var _z = (mask >> 4) & 0x3; var _w = (mask >> 6) & 0x3; - return SIMD.int32x4(t.storage_[_x], t.storage_[_y], t.storage_[_z], - t.storage_[_w]); + var storage = _PRIVATE._i32x4; + storage[0] = t.x_; + storage[1] = t.y_; + storage[2] = t.z_; + storage[3] = t.w_; + return SIMD.int32x4(storage[_x], storage[_y], storage[_z], storage[_w]); } /** @@ -536,23 +1123,41 @@ SIMD.int32x4.shuffle = function(t, mask) { * @return {int32x4} New instance of float32x4 with lanes shuffled. */ SIMD.int32x4.shuffleMix = function(t1, t2, mask) { + checkInt32x4(t1); + checkInt32x4(t2); var _x = (mask) & 0x3; var _y = (mask >> 2) & 0x3; var _z = (mask >> 4) & 0x3; var _w = (mask >> 6) & 0x3; - return SIMD.int32x4(t1.storage_[_x], t1.storage_[_y], t2.storage_[_z], - t2.storage_[_w]); -} - -/** - * @param {float32x4} + var storage = _PRIVATE._i32x8; + storage[0] = t1.x_; + storage[1] = t1.y_; + storage[2] = t1.z_; + storage[3] = t1.w_; + storage[4] = t2.x_; + storage[5] = t2.y_; + storage[6] = t2.z_; + storage[7] = t2.w_; + return SIMD.float32x4(storage[0 + _x], storage[0 + _y], + storage[4 + _z], storage[4 + _w]); +} + +/** + * @param {int32x4} t Selector mask. An instance of int32x4 + * @param {int32x4} trueValue Pick lane from here if corresponding + * selector lane is 0xFFFFFFFF + * @param {int32x4} falseValue Pick lane from here if corresponding + * selector lane is 0x0 + * @return {int32x4} Mix of lanes from trueValue or falseValue as + * indicated */ SIMD.int32x4.select = function(t, trueValue, falseValue) { - var tv = SIMD.float32x4.bitsToInt32x4(trueValue); - var fv = SIMD.float32x4.bitsToInt32x4(falseValue); - var tr = SIMD.int32x4.and(t, tv); - var fr = SIMD.int32x4.and(SIMD.int32x4.not(t), fv); - return SIMD.int32x4.bitsToFloat32x4(SIMD.int32x4.or(tr, fr)); + checkInt32x4(t); + checkInt32x4(trueValue); + checkInt32x4(falseValue); + var tr = SIMD.int32x4.and(t, trueValue); + var fr = SIMD.int32x4.and(SIMD.int32x4.not(t), falseValue); + return SIMD.int32x4.or(tr, fr); } /** @@ -562,6 +1167,7 @@ SIMD.int32x4.select = function(t, trueValue, falseValue) { * x lane replaced with {x}. */ SIMD.int32x4.withX = function(t, x) { + checkInt32x4(t); return SIMD.int32x4(x, t.y, t.z, t.w); } @@ -572,6 +1178,7 @@ SIMD.int32x4.withX = function(t, x) { * y lane replaced with {y}. */ SIMD.int32x4.withY = function(t, y) { + checkInt32x4(t); return SIMD.int32x4(t.x, y, t.z, t.w); } @@ -582,6 +1189,7 @@ SIMD.int32x4.withY = function(t, y) { * z lane replaced with {z}. */ SIMD.int32x4.withZ = function(t, z) { + checkInt32x4(t); return SIMD.int32x4(t.x, t.y, z, t.w); } @@ -591,6 +1199,7 @@ SIMD.int32x4.withZ = function(t, z) { * w lane replaced with {w}. */ SIMD.int32x4.withW = function(t, w) { + checkInt32x4(t); return SIMD.int32x4(t.x, t.y, t.z, w); } @@ -601,6 +1210,7 @@ SIMD.int32x4.withW = function(t, w) { * x lane replaced with {x}. */ SIMD.int32x4.withFlagX = function(t, flagX) { + checkInt32x4(t); var x = flagX ? 0xFFFFFFFF : 0x0; return SIMD.int32x4(x, t.y, t.z, t.w); } @@ -612,6 +1222,7 @@ SIMD.int32x4.withFlagX = function(t, flagX) { * y lane replaced with {y}. */ SIMD.int32x4.withFlagY = function(t, flagY) { + checkInt32x4(t); var y = flagY ? 0xFFFFFFFF : 0x0; return SIMD.int32x4(t.x, y, t.z, t.w); } @@ -623,6 +1234,7 @@ SIMD.int32x4.withFlagY = function(t, flagY) { * z lane replaced with {z}. */ SIMD.int32x4.withFlagZ = function(t, flagZ) { + checkInt32x4(t); var z = flagZ ? 0xFFFFFFFF : 0x0; return SIMD.int32x4(t.x, t.y, z, t.w); } @@ -634,6 +1246,7 @@ SIMD.int32x4.withFlagZ = function(t, flagZ) { * w lane replaced with {w}. */ SIMD.int32x4.withFlagW = function(t, flagW) { + checkInt32x4(t); var w = flagW ? 0xFFFFFFFF : 0x0; return SIMD.int32x4(t.x, t.y, t.z, w); } @@ -645,6 +1258,8 @@ SIMD.int32x4.withFlagW = function(t, flagW) { * the result of t == other. */ SIMD.int32x4.equal = function(t, other) { + checkInt32x4(t); + checkInt32x4(other); var cx = t.x == other.x; var cy = t.y == other.y; var cz = t.z == other.z; @@ -659,6 +1274,8 @@ SIMD.int32x4.equal = function(t, other) { * the result of t > other. */ SIMD.int32x4.greaterThan = function(t, other) { + checkInt32x4(t); + checkInt32x4(other); var cx = t.x > other.x; var cy = t.y > other.y; var cz = t.z > other.z; @@ -673,6 +1290,8 @@ SIMD.int32x4.greaterThan = function(t, other) { * the result of t < other. */ SIMD.int32x4.lessThan = function(t, other) { + checkInt32x4(t); + checkInt32x4(other); var cx = t.x < other.x; var cy = t.y < other.y; var cz = t.z < other.z; @@ -686,6 +1305,7 @@ SIMD.int32x4.lessThan = function(t, other) { * @return {int32x4} lanes in a shifted by bits. */ SIMD.int32x4.shiftLeft = function(a, bits) { + checkInt32x4(a); var x = a.x << bits; var y = a.y << bits; var z = a.z << bits; @@ -699,6 +1319,7 @@ SIMD.int32x4.shiftLeft = function(a, bits) { * @return {int32x4} lanes in a shifted by bits. */ SIMD.int32x4.shiftRightLogical = function(a, bits) { + checkInt32x4(a); var x = a.x >>> bits; var y = a.y >>> bits; var z = a.z >>> bits; @@ -712,6 +1333,7 @@ SIMD.int32x4.shiftRightLogical = function(a, bits) { * @return {int32x4} lanes in a shifted by bits. */ SIMD.int32x4.shiftRightArithmetic = function(a, bits) { + checkInt32x4(a); var x = a.x >> bits; var y = a.y >> bits; var z = a.z >> bits; @@ -719,31 +1341,6 @@ SIMD.int32x4.shiftRightArithmetic = function(a, bits) { return SIMD.int32x4(x, y, z, w); } -/** - * @param {int32x4} t An instance of int32x4. - * @return {float32x4} a bit-wise copy of t as a float32x4. - */ -SIMD.int32x4.bitsToFloat32x4 = function(t) { - var temp_storage = new Int32Array([t.storage_[0], t.storage_[1], t.storage_[2], t.storage_[3]]); - var alias = new Float32Array(temp_storage.buffer); - var fx4 = SIMD.float32x4.zero(); - fx4.storage_ = alias; - return fx4; -} - -/** - * @param {int32x4} t An instance of int32x4. - * @return {float32x4} with a float to integer conversion copy of t. - */ -SIMD.int32x4.toFloat32x4 = function(t) { - var a = float32x4.zero(); - a.storage_[0] = t.storage_[0]; - a.storage_[1] = t.storage_[1]; - a.storage_[2] = t.storage_[2]; - a.storage_[3] = t.storage_[3]; - return a; -} - Object.defineProperty(SIMD, 'XXXX', { get: function() { return 0x0; } }); Object.defineProperty(SIMD, 'XXXY', { get: function() { return 0x40; } }); Object.defineProperty(SIMD, 'XXXZ', { get: function() { return 0x80; } }); @@ -1001,20 +1598,25 @@ Object.defineProperty(SIMD, 'WWWY', { get: function() { return 0x7F; } }); Object.defineProperty(SIMD, 'WWWZ', { get: function() { return 0xBF; } }); Object.defineProperty(SIMD, 'WWWW', { get: function() { return 0xFF; } }); +Object.defineProperty(SIMD, 'XX', { get: function() { return 0x0; } }); +Object.defineProperty(SIMD, 'XY', { get: function() { return 0x2; } }); +Object.defineProperty(SIMD, 'YX', { get: function() { return 0x1; } }); +Object.defineProperty(SIMD, 'YY', { get: function() { return 0x3; } }); + Object.defineProperty(SIMD.float32x4.prototype, 'x', { - get: function() { return this.storage_[0]; } + get: function() { return this.x_; } }); Object.defineProperty(SIMD.float32x4.prototype, 'y', { - get: function() { return this.storage_[1]; } + get: function() { return this.y_; } }); Object.defineProperty(SIMD.float32x4.prototype, 'z', { - get: function() { return this.storage_[2]; } + get: function() { return this.z_; } }); Object.defineProperty(SIMD.float32x4.prototype, 'w', - { get: function() { return this.storage_[3]; } + { get: function() { return this.w_; } }); /** @@ -1030,36 +1632,55 @@ Object.defineProperty(SIMD.float32x4.prototype, 'signMask', { } }); +Object.defineProperty(SIMD.float64x2.prototype, 'x', { + get: function() { return this.x_; } +}); + +Object.defineProperty(SIMD.float64x2.prototype, 'y', { + get: function() { return this.y_; } +}); + +/** + * Extract the sign bit from each lane return them in the first 2 bits. + */ +Object.defineProperty(SIMD.float64x2.prototype, 'signMask', { + get: function() { + var mx = this.x < 0.0 ? 1 : 0; + var my = this.y < 0.0 ? 1 : 0; + return mx | my << 1; + } +}); + Object.defineProperty(SIMD.int32x4.prototype, 'x', { - get: function() { return this.storage_[0]; } + get: function() { return this.x_; } }); Object.defineProperty(SIMD.int32x4.prototype, 'y', { - get: function() { return this.storage_[1]; } + get: function() { return this.y_; } }); Object.defineProperty(SIMD.int32x4.prototype, 'z', { - get: function() { return this.storage_[2]; } + get: function() { return this.z_; } }); Object.defineProperty(SIMD.int32x4.prototype, 'w', - { get: function() { return this.storage_[3]; } + { get: function() { return this.w_; } }); Object.defineProperty(SIMD.int32x4.prototype, 'flagX', { - get: function() { return this.storage_[0] != 0x0; } + get: function() { return this.x_ != 0x0; } }); Object.defineProperty(SIMD.int32x4.prototype, 'flagY', { - get: function() { return this.storage_[1] != 0x0; } + get: function() { return this.y_ != 0x0; } }); Object.defineProperty(SIMD.int32x4.prototype, 'flagZ', { - get: function() { return this.storage_[2] != 0x0; } + get: function() { return this.z_ != 0x0; } }); Object.defineProperty(SIMD.int32x4.prototype, 'flagW', - { get: function() { return this.storage_[3] != 0x0; } + { get: function() { return this.w_ != 0x0; } }); /** @@ -1067,10 +1688,10 @@ Object.defineProperty(SIMD.int32x4.prototype, 'flagW', */ Object.defineProperty(SIMD.int32x4.prototype, 'signMask', { get: function() { - var mx = (this.storage_[0] & 0x80000000) >>> 31; - var my = (this.storage_[1] & 0x80000000) >>> 31; - var mz = (this.storage_[2] & 0x80000000) >>> 31; - var mw = (this.storage_[3] & 0x80000000) >>> 31; + var mx = (this.x_ & 0x80000000) >>> 31; + var my = (this.y_ & 0x80000000) >>> 31; + var mz = (this.z_ & 0x80000000) >>> 31; + var mw = (this.w_ & 0x80000000) >>> 31; return mx | my << 1 | mz << 2 | mw << 3; } }); From 8367ef671fe83029a93321fab1c86d70f58593dd Mon Sep 17 00:00:00 2001 From: Ningxin Hu Date: Mon, 18 Aug 2014 15:51:43 -0700 Subject: [PATCH 04/60] Update SIMD.js code generation due to API update. --- src/library.js | 36 +++++++++++++-------------- src/parseTools.js | 4 +-- system/include/emscripten/emmintrin.h | 8 +++--- system/include/emscripten/vector.h | 8 +++--- 4 files changed, 28 insertions(+), 28 deletions(-) diff --git a/src/library.js b/src/library.js index 82059d5e9790e..88ef3ee642366 100644 --- a/src/library.js +++ b/src/library.js @@ -8654,7 +8654,7 @@ LibraryManager.library = { //============================ emscripten_float32x4_signmask__inline: function(a) { - return 'SIMD.float32x4.bitsToInt32x4(' + a + ').signMask'; + return a + '.signMask'; }, emscripten_float32x4_min__inline: function(a, b) { @@ -8670,55 +8670,55 @@ LibraryManager.library = { }, emscripten_float32x4_lessThan__inline: function(a, b) { - return 'SIMD.int32x4.bitsToFloat32x4(SIMD.float32x4.lessThan(' + a + ', ' + b + '))'; + return 'SIMD.float32x4.fromInt32x4Bits(SIMD.float32x4.lessThan(' + a + ', ' + b + '))'; }, emscripten_float32x4_lessThanOrEqual__inline: function(a, b) { - return 'SIMD.int32x4.bitsToFloat32x4(SIMD.float32x4.lessThanOrEqual(' + a + ', ' + b + '))'; + return 'SIMD.float32x4.fromInt32x4Bits(SIMD.float32x4.lessThanOrEqual(' + a + ', ' + b + '))'; }, emscripten_float32x4_equal__inline: function(a, b) { - return 'SIMD.int32x4.bitsToFloat32x4(SIMD.float32x4.equal(' + a + ', ' + b + '))'; + return 'SIMD.float32x4.fromInt32x4Bits(SIMD.float32x4.equal(' + a + ', ' + b + '))'; }, emscripten_float32x4_greaterThanOrEqual__inline: function(a, b) { - return 'SIMD.int32x4.bitsToFloat32x4(SIMD.float32x4.greaterThanOrEqual(' + a + ', ' + b + '))'; + return 'SIMD.float32x4.fromInt32x4Bits(SIMD.float32x4.greaterThanOrEqual(' + a + ', ' + b + '))'; }, emscripten_float32x4_greaterThan__inline: function(a, b) { - return 'SIMD.int32x4.bitsToFloat32x4(SIMD.float32x4.greaterThan(' + a + ', ' + b + '))'; + return 'SIMD.float32x4.fromInt32x4Bits(SIMD.float32x4.greaterThan(' + a + ', ' + b + '))'; }, emscripten_float32x4_and__inline: function(a, b) { - return 'SIMD.int32x4.bitsToFloat32x4(SIMD.int32x4.and(SIMD.float32x4.bitsToInt32x4(' + a + '), SIMD.float32x4.bitsToInt32x4(' + b + ')))'; + return 'SIMD.float32x4.fromInt32x4Bits(SIMD.float32x4.and(' + a + ', ' + b + '))'; }, emscripten_float32x4_andNot__inline: function(a, b) { - return 'SIMD.int32x4.bitsToFloat32x4(SIMD.int32x4.and(SIMD.int32x4.not(SIMD.float32x4.bitsToInt32x4(' + a + ')), SIMD.float32x4.bitsToInt32x4(' + b + ')))'; + return 'SIMD.float32x4.fromInt32x4Bits(SIMD.float32x4.and(SIMD.float32x4.not(' + a + '), ' + b + '))'; }, emscripten_float32x4_or__inline: function(a, b) { - return 'SIMD.int32x4.bitsToFloat32x4(SIMD.int32x4.or(SIMD.float32x4.bitsToInt32x4(' + a + '), SIMD.float32x4.bitsToInt32x4(' + b + ')))'; + return 'SIMD.float32x4.fromInt32x4Bits(SIMD.float32x4.or(' + a + ', ' + b + '))'; }, emscripten_float32x4_xor__inline: function(a, b) { - return 'SIMD.int32x4.bitsToFloat32x4(SIMD.int32x4.xor(SIMD.float32x4.bitsToInt32x4(' + a + '), SIMD.float32x4.bitsToInt32x4(' + b + ')))'; + return 'SIMD.float32x4.fromInt32x4Bits(SIMD.float32x4.xor(' + a + ', ' + b + '))'; }, - emscripten_int32x4_bitsToFloat32x4__inline: function(a) { - return 'SIMD.int32x4.bitsToFloat32x4(' + a + ')'; + emscripten_float32x4_fromInt32x4Bits__inline: function(a) { + return 'SIMD.float32x4.fromInt32x4Bits(' + a + ')'; }, - emscripten_int32x4_toFloat32x4__inline: function(a) { - return 'SIMD.int32x4.toFloat32x4(' + a + ')'; + emscripten_float32x4_fromInt32x4__inline: function(a) { + return 'SIMD.float32x4.fromInt32x4(' + a + ')'; }, - emscripten_float32x4_bitsToInt32x4__inline: function(a) { - return 'SIMD.float32x4.bitsToInt32x4(' + a + ')'; + emscripten_int32x4_fromFloat32x4Bits__inline: function(a) { + return 'SIMD.int32x4.fromFloat32x4Bits(' + a + ')'; }, - emscripten_float32x4_toInt32x4__inline: function(a) { - return 'SIMD.float32x4.toInt32x4(' + a + ')'; + emscripten_int32x4_fromFloat32x4__inline: function(a) { + return 'SIMD.int32x4.fromFloat32x4(' + a + ')'; }, //============================ diff --git a/src/parseTools.js b/src/parseTools.js index ececf477683cf..c5c4384bda79d 100644 --- a/src/parseTools.js +++ b/src/parseTools.js @@ -2387,11 +2387,11 @@ function processMathop(item) { var outType = item.type; if (inType === '<4 x float>') { assert(outType === '<4 x i32>'); - return 'SIMD.float32x4.bitsToInt32x4(' + idents[0] + ')'; + return 'SIMD.int32x4.fromFloat32x4Bits(' + idents[0] + ')'; } else { assert(inType === '<4 x i32>'); assert(outType === '<4 x float>'); - return 'SIMD.int32x4.bitsToFloat32x4(' + idents[0] + ')'; + return 'SIMD.float32x4.fromInt32x4Bits(' + idents[0] + ')'; } } case 'and': return 'SIMD.int32x4.and(' + idents[0] + ',' + idents[1] + ')'; diff --git a/system/include/emscripten/emmintrin.h b/system/include/emscripten/emmintrin.h index 31265db803494..b3278a9b2fbe0 100644 --- a/system/include/emscripten/emmintrin.h +++ b/system/include/emscripten/emmintrin.h @@ -65,23 +65,23 @@ _mm_sub_epi32(__m128i a, __m128i b) static __inline__ __m128 __attribute__((__always_inline__)) _mm_castsi128_ps(__m128i a) { - return emscripten_int32x4_bitsToFloat32x4(a); + return emscripten_float32x4_fromInt32x4Bits(a); } static __inline__ __m128 __attribute__((__always_inline__)) _mm_cvtepi32_ps(__m128i a) { - return emscripten_int32x4_toFloat32x4(a); + return emscripten_float32x4_fromInt32x4(a); } static __inline__ __m128i __attribute__((__always_inline__)) _mm_castps_si128(__m128 a) { - return emscripten_float32x4_bitsToInt32x4(a); + return emscripten_int32x4_fromFloat32x4Bits(a); } static __inline__ __m128i __attribute__((__always_inline__)) _mm_cvtps_epi32(__m128 a) { - return emscripten_float32x4_toInt32x4(a); + return emscripten_int32x4_fromFloat32x4(a); } \ No newline at end of file diff --git a/system/include/emscripten/vector.h b/system/include/emscripten/vector.h index cf26a5d66fca6..39f41764ea290 100644 --- a/system/include/emscripten/vector.h +++ b/system/include/emscripten/vector.h @@ -23,10 +23,10 @@ float32x4 emscripten_float32x4_andNot(float32x4 a, float32x4 b); float32x4 emscripten_float32x4_or(float32x4 a, float32x4 b); float32x4 emscripten_float32x4_xor(float32x4 a, float32x4 b); -float32x4 emscripten_int32x4_bitsToFloat32x4(int32x4 a); -float32x4 emscripten_int32x4_toFloat32x4(int32x4 a); -int32x4 emscripten_float32x4_bitsToInt32x4(float32x4 a); -int32x4 emscripten_float32x4_toInt32x4(float32x4 a); +float32x4 emscripten_float32x4_fromInt32x4Bits(int32x4 a); +float32x4 emscripten_float32x4_fromInt32x4(int32x4 a); +int32x4 emscripten_int32x4_fromFloat32x4Bits(float32x4 a); +int32x4 emscripten_int32x4_fromFloat32x4(float32x4 a); #ifdef __cplusplus } From 3e9d7908048446648510b5942ca9363a8c15574c Mon Sep 17 00:00:00 2001 From: Antoine Lambert Date: Wed, 20 Aug 2014 11:24:18 +0200 Subject: [PATCH 05/60] add javascript implementation of glutSetCursor function --- src/library_glut.js | 58 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/src/library_glut.js b/src/library_glut.js index d6293d85ff54e..8ebe79ee511de 100644 --- a/src/library_glut.js +++ b/src/library_glut.js @@ -432,6 +432,64 @@ var LibraryGLUT = { GLUT.mouseFunc = func; }, + glutSetCursor: function(cursor) { + var cursorStyle = 'auto'; + switch(cursor) { + case 0x0002: /* GLUT_CURSOR_INFO */ + cursorStyle = 'pointer'; + break; + case 0x0004: /* GLUT_CURSOR_HELP */ + cursorStyle = 'help'; + break; + case 0x0007: /* GLUT_CURSOR_WAIT */ + cursorStyle = 'wait'; + break; + case 0x0008: /* GLUT_CURSOR_TEXT */ + cursorStyle = 'text'; + break; + case 0x0009: /* GLUT_CURSOR_CROSSHAIR */ + case 0x0066: /* GLUT_CURSOR_FULL_CROSSHAIR */ + cursorStyle = 'crosshair'; + break; + case 0x000A: /* GLUT_CURSOR_UP_DOWN */ + cursorStyle = 'ns-resize'; + break; + case 0x000B: /* GLUT_CURSOR_LEFT_RIGHT */ + cursorStyle = 'ew-resize'; + break; + case 0x000C: /* GLUT_CURSOR_TOP_SIDE */ + cursorStyle = 'n-resize'; + break; + case 0x000D: /* GLUT_CURSOR_BOTTOM_SIDE */ + cursorStyle = 's-resize'; + break; + case 0x000E: /* GLUT_CURSOR_LEFT_SIDE */ + cursorStyle = 'w-resize'; + break; + case 0x000F: /* GLUT_CURSOR_RIGHT_SIDE */ + cursorStyle = 'e-resize'; + break; + case 0x0010: /* GLUT_CURSOR_TOP_LEFT_CORNER */ + cursorStyle = 'nw-resize'; + break; + case 0x0011: /* GLUT_CURSOR_TOP_RIGHT_CORNER */ + cursorStyle = 'ne-resize'; + break; + case 0x0012: /* GLUT_CURSOR_BOTTOM_RIGHT_CORNER */ + cursorStyle = 'se-resize'; + break; + case 0x0013: /* GLUT_CURSOR_BOTTOM_LEFT_CORNER */ + cursorStyle = 'sw-resize'; + break; + case 0x0065: /* GLUT_CURSOR_NONE */ + cursorStyle = 'none'; + break; + default: + break; + } + Module['canvas'].style.cursor = cursorStyle; + }, + glutCreateWindow__deps: ['$Browser'], glutCreateWindow: function(name) { var contextAttributes = { From 31ef456a4f2ef976e685f16ee2ddcac0ae48af86 Mon Sep 17 00:00:00 2001 From: Antoine Lambert Date: Wed, 20 Aug 2014 11:36:26 +0200 Subject: [PATCH 06/60] fix indentation --- src/library_glut.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/library_glut.js b/src/library_glut.js index 8ebe79ee511de..1a3bb21c0c31a 100644 --- a/src/library_glut.js +++ b/src/library_glut.js @@ -483,7 +483,7 @@ var LibraryGLUT = { break; case 0x0065: /* GLUT_CURSOR_NONE */ cursorStyle = 'none'; - break; + break; default: break; } From 7075ff4161b4ab4ae62c8cc4c938b84430a5339f Mon Sep 17 00:00:00 2001 From: Antoine Lambert Date: Wed, 20 Aug 2014 15:16:31 +0200 Subject: [PATCH 07/60] handle all possible GLUT cursor value and throw an exception when an invalid one is provided --- src/library_glut.js | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/src/library_glut.js b/src/library_glut.js index 1a3bb21c0c31a..d764582d4e5fc 100644 --- a/src/library_glut.js +++ b/src/library_glut.js @@ -435,12 +435,27 @@ var LibraryGLUT = { glutSetCursor: function(cursor) { var cursorStyle = 'auto'; switch(cursor) { + case 0x0000: /* GLUT_CURSOR_RIGHT_ARROW */ + // No equivalent css cursor style, fallback to 'auto' + break; + case 0x0001: /* GLUT_CURSOR_LEFT_ARROW */ + // No equivalent css cursor style, fallback to 'auto' + break; case 0x0002: /* GLUT_CURSOR_INFO */ cursorStyle = 'pointer'; break; + case 0x0003: /* GLUT_CURSOR_DESTROY */ + // No equivalent css cursor style, fallback to 'auto' + break; case 0x0004: /* GLUT_CURSOR_HELP */ cursorStyle = 'help'; break; + case 0x0005: /* GLUT_CURSOR_CYCLE */ + // No equivalent css cursor style, fallback to 'auto' + break; + case 0x0006: /* GLUT_CURSOR_SPRAY */ + // No equivalent css cursor style, fallback to 'auto' + break; case 0x0007: /* GLUT_CURSOR_WAIT */ cursorStyle = 'wait'; break; @@ -481,11 +496,13 @@ var LibraryGLUT = { case 0x0013: /* GLUT_CURSOR_BOTTOM_LEFT_CORNER */ cursorStyle = 'sw-resize'; break; + case 0x0064: /* GLUT_CURSOR_INHERIT */ + break; case 0x0065: /* GLUT_CURSOR_NONE */ cursorStyle = 'none'; break; default: - break; + throw "glutSetCursor: Unknown cursor type: " + cursor; } Module['canvas'].style.cursor = cursorStyle; }, From 7b7aeb98405fbf48900925a790c9c4a59b5b568f Mon Sep 17 00:00:00 2001 From: hamishwillee Date: Thu, 21 Aug 2014 12:55:42 +1000 Subject: [PATCH 08/60] Addition of Module reference and cross linking to it from elsewhere. Removal from Interacting with code --- .../docs/api_reference/Filesystem-API.rst | 4 +- site/source/docs/api_reference/index.rst | 3 + site/source/docs/api_reference/module.rst | 79 +++++++++++++++++++ .../source/docs/api_reference/preamble.js.rst | 2 +- .../Interacting-with-code.rst | 58 +++++--------- site/source/docs/tools_reference/emcc.rst | 31 ++++---- 6 files changed, 120 insertions(+), 57 deletions(-) create mode 100644 site/source/docs/api_reference/module.rst diff --git a/site/source/docs/api_reference/Filesystem-API.rst b/site/source/docs/api_reference/Filesystem-API.rst index 98e6b8bf5c475..65b04b3025656 100644 --- a/site/source/docs/api_reference/Filesystem-API.rst +++ b/site/source/docs/api_reference/Filesystem-API.rst @@ -1,7 +1,7 @@ .. _Filesystem-API: ===================================== -Filesystem API (under-construction) +File System API (under-construction) ===================================== File I/O in Emscripten is provided by the `FS `_ library. It is used internally for all of Emscripten's **libc** and **libcxx** file I/O. @@ -97,7 +97,7 @@ By default: - ``stdout`` will use a ``print`` function if one such is defined, printing to the terminal in command line engines and to the browser console in browsers that have a console (again, line-buffered). - ``stderr`` will use the same output function as ``stdout``. -.. note:: All the configuration should be done before the main ``run()`` method is executed, typically by implementing ``Module.preRun``, see :ref:`Interacting-with-code`. +.. note:: All the configuration should be done before the main ``run()`` method is executed, typically by implementing :js:attr:`Module.preRun`, see :ref:`Interacting-with-code`. .. js:function:: FS.init(input, output, error) diff --git a/site/source/docs/api_reference/index.rst b/site/source/docs/api_reference/index.rst index d6379d25b09b0..a624cb8af2907 100644 --- a/site/source/docs/api_reference/index.rst +++ b/site/source/docs/api_reference/index.rst @@ -18,6 +18,8 @@ This section lists Emscripten's public API, organised by header file. At very hi - **Filesystem-API (library_fs.js)**: *APIs for (primarily) synchronous File I/O.* +- **Module**: **User-populated global JavaScript object, with attributes that Emscripten-generated code calls at various points in its execution.** + - **val.h**: *Embind APIs for* **HamishW** - add description - **bind.h**: *Embind APIs for* **HamishW** - add description @@ -34,6 +36,7 @@ This section lists Emscripten's public API, organised by header file. At very hi html5.h preamble.js Filesystem-API + module val.h bind.h advanced-apis diff --git a/site/source/docs/api_reference/module.rst b/site/source/docs/api_reference/module.rst new file mode 100644 index 0000000000000..a618968d39786 --- /dev/null +++ b/site/source/docs/api_reference/module.rst @@ -0,0 +1,79 @@ +.. _module: + +==================================== +Module object (ready-for-review) +==================================== + +``Module`` is a global JavaScript object, with attributes that Emscripten-generated code calls at various points in its execution. + +Developers provide an implementation of ``Module`` to control the execution of code. For example, to define how notification messages from Emscripten are displayed, developers implement the :js:attr:`Module.print` attribute. + +.. note:: ``Module`` is also used to provide access functions (see :js:func:`ccall`) in a way that avoids issues with function name minification at higher optimisation levels. These functions are documented as part of their own APIs. + +.. contents:: Table of Contents + :local: + :depth: 1 + + +.. _module-creating: + +Creating Module +================ + +Use :ref:`emcc's ` ``--pre-js`` option to add JavaScript code that defines (or extends) the ``Module`` object with the behaviour you need. + +When generating only JavaScript, no ``Module`` object is created by default, and the behaviour is entirely defined by the developer. For example, creating a ``Module`` object with the following code will cause all notifications from the program to be calls to ``alert()``. + + :: + + var Module = { + 'print': function(text) { alert(text) } + }; + +.. important:: If you run closure compiler on your code (which is done by default in optimisation level :ref:`-02 ` and higher), you will need quotation marks around the properties of ``Module`` as in the example above (and you need to run closure on the compiled code together with the declaration of ``Module``). + +When generating HTML, Emscripten creates a ``Module`` object with default methods (see `src/shell.html `_). In this case you should again use ``--pre-js``, but this time to add properties to the existing ``Module`` object. + + + +Affecting execution +=================== + +The following ``Module`` attributes affect code execution. + + +.. js:attribute:: Module.print + + Called when something is printed to standard output. + + + +.. js:attribute:: Module.arguments + + The commandline arguments. The value of ``arguments`` is what is returned if compiled code checks ``argc`` and ``argv``. + + +.. js:attribute:: Module.preInit + + A function (or array of functions) that must be called before global initializers run, but after basic initialization of the JavaScript runtime. This is typically used for :ref:`File System operations ` and is called befroe C++ initializers have been run. + + +.. js:attribute:: Module.preRun + + A function (or array of functions) to call right before calling ``run()``, but after defining and setting up the environment, including global initializers. This is useful, for example, to set up directories and files using the :ref:`Filesystem-API` (since that needs the FileSystem API to be defined, but also needs to be done before the program starts to run. + + .. note:: If code needs to affect global initializers, it should instead be run using :js:attr:`preInit`. + + +.. js:attribute:: Module.noInitialRun + + If set to ``true``, ``main()`` will not be automatically called (you can do so yourself later). The program will still call global initializers, set up memory initialization, and so forth. + + +.. js:attribute:: Module.noExitRuntime + + If set to ``true``, the runtime is not shut down after ``run`` completes. Shutting down the runtime calls shutdown callbacks, for example ``atexit`` calls. If you want to be able to continue to use the code after ``run()`` finishes, it is safer to set this. + + + + diff --git a/site/source/docs/api_reference/preamble.js.rst b/site/source/docs/api_reference/preamble.js.rst index 02e3e5eeadb6c..1da8db591d808 100644 --- a/site/source/docs/api_reference/preamble.js.rst +++ b/site/source/docs/api_reference/preamble.js.rst @@ -4,7 +4,7 @@ preamble.js The JavaScript APIs in `preamble.js `_ provide programmatic access for interacting with the compiled C code, including: calling compiled C functions, accessing memory, converting pointers to JavaScript ``Strings`` and ``Strings`` to pointers (with different encodings/formats), and other convenience functions. -.. note:: All functions should be called though the ``Module`` object (for example: ``Module.functionName``). At optimisation ``-O2`` (and higher) function names are minified by the closure compiler, and calling them directly will fail. +.. note:: All functions should be called though the :ref:`Module ` object (for example: ``Module.functionName``). At optimisation ``-O2`` (and higher) function names are minified by the closure compiler, and calling them directly will fail. .. contents:: Table of Contents diff --git a/site/source/docs/coding/connecting_cpp_and_javascript/Interacting-with-code.rst b/site/source/docs/coding/connecting_cpp_and_javascript/Interacting-with-code.rst index a20fccb4d31dc..8136b4dd9fb17 100644 --- a/site/source/docs/coding/connecting_cpp_and_javascript/Interacting-with-code.rst +++ b/site/source/docs/coding/connecting_cpp_and_javascript/Interacting-with-code.rst @@ -6,16 +6,13 @@ Interacting with code (wiki-import) .. note:: This article was migrated from the wiki (Fri, 25 Jul 2014 04:21) and is now the "master copy" (the version in the wiki will be deleted). It may not be a perfect rendering of the original but we hope to fix that soon! -Interacting with Compiled Code -============================== - (If you are looking for how compiled code interacts with the browser environment, see :ref:`Emscripten-Browser-Environment`.) There are various ways to connect and interact between JS and compiled C++ in JS. An overview appears in the second half of these slides: http://kripken.github.io/mloc\_emscripten\_talk/qcon.html Calling Compiled Functions From Normal JavaScript -------------------------------------------------- +================================================= It's easy to call compiled code from normal JavaScript. For example, run this command in the Emscripten home directory: @@ -46,7 +43,7 @@ Some things to keep in mind with :js:func:`ccall` and :js:func:`cwrap`: **Note:** you need ``_`` at the beginning of the functions when exporting (but not with ccall), and note also that you need to use ``Module.ccall`` and not :js:func:`ccall` by itself, since closure will minify the function name, leaving only the Module object where we export names. Accessing Memory ----------------- +================ You can access memory using :js:func:`getValue(ptr, type) ` and :js:func:`setValue(ptr, value, type) `. The first argument is a pointer, a number representing a memory address. ``type`` must be an LLVM IR type, one of ``i8,i16,i32,i64,float,double`` or a pointer type like ``i8*`` (or just ``*``). Note that the types here are not as in :js:func:`ccall` and :js:func:`cwrap` - this is a lower-level operation, and we do need to care what specific integer etc. type is being used. @@ -62,7 +59,7 @@ You can also access memory 'directly' by manipulating the arrays that represent That allocates a buffer, copies in some data, then calls a C function to process the data, and finally frees the buffer. Here ``my_function`` is a C function that receives a single integer parameter (could be a pointer as well, as they are just 32-bit integers for us), and returns an integer as well, something like ``int my_function(char *buf)``. Calling JavaScript From C/C++ ------------------------------ +============================= The most direct way is to just use :c:func:`emscripten_run_script`, which basically runs some JS code from C/C++ using eval. So ``emscripten_run_script("alert('hi')");`` will show an alert with 'hi' (note: this calls ``alert`` which is present in browsers, but not in node or other JS shells. You can call ``Module.print`` to print to stdout). This is not very fast though. A faster alternative is to write "inline JavaScript", basically the same as inline assembly would be used, for example @@ -127,22 +124,22 @@ You can use the emcc option ``--js-library`` to add a file with such code, inste - JS libraries can declare dependencies (``__deps``, see examples in ``library*.js``), however those are only for other JS libraries. If a JS library depends on a compiled C library (like most of libc), you must edit ``src/deps_info.json``, see ``tools/system_libs.py`` (search for deps\_info). Calling JS functions as function pointers from C -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------------------------- You can use ``Runtime.addFunction`` to return an integer value that represents a function pointer. Passing that integer to C code then lets it call that value as a function pointer, and the JS function you sent to ``Runtime.addFunction`` will be called. See ``test_add_function`` in ``tests/test_core.py`` for an example. WebIDL Binder -------------- +============= The :ref:`WebIDL-Binder` is a tool to make C++ classes usable from JS as JS classes. It is used to port Bullet Physics to the web in the **ammo.js** project, and is a fairly simple lightweight approach to binding between the two languages. Embind ------- +====== Embind is a method to communicate from JS to C++ and C++ to JS, in a C++-like manner (whereas JS libraries are using C APIs, and just one direction). The only downside is that it is not as lightweight as JS libraries or the WebIDL binder. Docs: :ref:`embind`. -Other Methods -------------- +Other methods +============= You can directly interact in various other ways with the compiled code: @@ -152,44 +149,25 @@ You can directly interact in various other ways with the compiled code: - There are various other convenience functions, see **preamble.js** (that file will be included with the generated code). - For filesystem-related manners, see the :ref:`Filesystem-Guide`. -Affecting Execution -------------------- - -You can affect how code runs by creating an object called ``Module`` before the compiled script. Certain properties on ``Module`` can then have various effects: - -- ``arguments``: The commandline arguments (if the compiled code checks ``argc``, ``argv``, it will be seeing ``arguments``) -- ``print``: Called when something is printed to standard output. -- ``preInit``: A function (or array of functions) to call before global initializers run, but after basic initialization of the JS runtime (so you can do ``FS.*`` stuff, but no C++ initializers were called yet). -- ``preRun``: A function (or array of functions) to call right before calling ``run``, but after defining and setting up the environment, including global initializers. This is useful, for example, to set up directories and files using the FileSystem API (since that needs the FileSystem API to be defined, but also needs to be done before the program starts to run; if you need to affect global initializers, though, you should use preInit). -- ``noInitialRun``: If set to true, ``main()`` will not be called. The program will still call global initializers, set up memory initialization, and so forth. You can then call ``main()`` yourself later. -- ``noExitRuntime``: If set to true, the runtime is not shut down after ``run`` is called. Shutting down the runtime calls shutdown callbacks, for example ``atexit`` calls. If you want to be able to continue to use the code after ``run`` finishes, it is safer to set this. - -For example, - -:: - - var Module = { - 'print': function(text) { alert(text) } - }; +Affecting execution +=================== -This will cause all printouts from the program to be calls to ``alert``. +``Module`` is a global JavaScript object, with attributes that Emscripten-generated code calls at various points in its execution. -**Important**: If you run closure compiler on your code (which is done by default in ``-O2`` and above), you will need quotation marks around the properties of ``Module`` as in the example above (and you need to run closure on the compiled code together with the declaration of ``Module``). +Developers provide an implementation of ``Module`` to control, for example, how notifications from Emscripten are displayed, which files that are loaded before the main loop is run, etc. For more information see :ref:`module`. -Setting Module -~~~~~~~~~~~~~~ -When generating just JavaScript, no Module object is created. So you can use emcc's ``--pre-js`` to add some JS code that defines the Module object with the stuff you need. +Environment variables +============================== -When generating HTML, a Module object is created for you and filled with some defaults for printing, etc. (compile a little hello world example to see, or view ``src/shell.html``). The simplest thing is to use ``--pre-js`` to add some JS code that adds properties to that existing Module object. +Sometimes compiled code needs to access environment variables (for instance, in C, by calling the ``getenv()`` function). Just as with the file system, Emscripten generated JavaScript cannot access the computer's environment variables directly, so a virtualised environment is provided. -Environment variables -~~~~~~~~~~~~~~~~~~~~~ +The JavaScript object ``ENV`` contains these virtualised environment variables, and by modifying it you can pass variables to your compiled code. Care must be taken to ensure that the ``ENV`` variable has been initialised by Emscripten before it is modified - using :js:attr:`Module.preRun` is a convenient way to do this. -Sometimes, the code you are compiling will want to access environment variables (for instance, in C, by calling the ``getenv()`` function). Just as with the filesystem, emscripten generated JavaScript cannot access the computer's environment variables so a virtualised environment is provided. The JavaScript object ``ENV`` contains these virtualised environment variables, and by modifying it you can pass variables to your compiled code. Care must be taken to ensure that the ``ENV`` variable has been initialised by Emscripten before it is modified - using ``Module.preRun`` is a convenient way to do this. For example to set an environment variable ``MY_FILE_ROOT`` to be ``"/usr/lib/test/"`` you could add +For example to set an environment variable ``MY_FILE_ROOT`` to be ``"/usr/lib/test/"`` you could add the following JavaScript to your :ref:`setup code `: .. code:: javascript Module.preRun.push(function() {ENV.MY_FILE_ROOT = "/usr/lib/test"}) -to your setup code, as described above. + diff --git a/site/source/docs/tools_reference/emcc.rst b/site/source/docs/tools_reference/emcc.rst index b7e4abc022cf7..585910c85f002 100644 --- a/site/source/docs/tools_reference/emcc.rst +++ b/site/source/docs/tools_reference/emcc.rst @@ -1,13 +1,11 @@ .. _emccdoc: -========================================================= -Emscripten Compiler Frontend (emcc) (under-construction) -========================================================= +====================================================== +Emscripten Compiler Frontend (emcc) (ready-for-review) +====================================================== **This document provides the command syntax for the Emscription Compiler Frontend.** -.. comment - The information in this page was output by running ``emcc --help`` on the version of *emcc* in the Emscripten 1.20.0 SDK. The most recent version is `emcc (master) `_ - Purpose ============================================ @@ -23,10 +21,6 @@ Command line syntax The input file(s) can be either source code files that *Clang* can handle (C or C++), LLVM bitcode in binary form, or LLVM assembly files in human-readable form. -Supported targets include: llvm bitcode, JavaScript, NOT elf (autoconf likes to see elf above to enable shared object support). - -.. todo:: **HamishW** The line above makes no sense. Checking with Alon. - Arguments --------- @@ -49,6 +43,7 @@ Options that are modified or new in *emcc* are listed below: ``-O0`` No optimizations (default). This is the recommended setting for starting to port a project, as it includes various assertions. +.. _emcc-O1: ``-O1`` Simple optimizations. These include using **asm.js**, LLVM ``-O1`` optimizations, relooping, removing runtime assertions and C++ exception catching, and enabling ``-s ALIASING_FUNCTION_POINTERS=1``. This is the recommended setting when you want a reasonably optimized build that is generated as quickly as possible (it builds much faster than ``-O2``). @@ -57,6 +52,8 @@ Options that are modified or new in *emcc* are listed below: - For details on the affects of different opt levels, see ``apply_opt_level()`` in `tools/shared.py `_ and also `src/settings.js `_. - To re-enable C++ exception catching, use ``-s DISABLE_EXCEPTION_CATCHING=0``. + +.. _emcc-O2: ``-O2`` Like ``-O1``, but with various JavaScript-level optimizations and LLVM ``-O3`` optimizations. @@ -69,6 +66,8 @@ Options that are modified or new in *emcc* are listed below: ``-Oz`` Like ``-Os``, but reduces code size even further. +.. _emcc-O3: + ``-O3`` Like ``-O2``, but with additional JavaScript optimizations that can take a significant amount of compilation time and/or are relatively new. @@ -167,7 +166,9 @@ Options that are modified or new in *emcc* are listed below: - If closure compiler hits an out-of-memory, try adjusting ``JAVA_HEAP_SIZE`` in the environment (for example, to 4096m for 4GB). - Closure is only run if JavaScript opts are being done (``-O2`` or above, or ``--js-opts 1``). - + +.. _emcc-pre-js: + ``--pre-js `` Specify a file whose contents are added before the generated code. This is done *before* optimization, so it will be minified properly if the *Closure Compiler* is run. @@ -197,7 +198,7 @@ Options that are modified or new in *emcc* are listed below: For more information about the ``--preload-file`` options, see :ref:`Filesystem-Guide`. ``--exclude-file `` - Files and directories to be excluded from :ref:`--embed-file ` and :ref:`--preload-file `. Wildcard is supported. + Files and directories to be excluded from :ref:`--embed-file ` and :ref:`--preload-file `. Wildcards (*) are supported. ``--shell-file `` The path name to a skeleton HTML file used when generating HTML output. The shell file used needs to have this token inside it: ``{{{ SCRIPT }}}``. @@ -276,8 +277,8 @@ Options that are modified or new in *emcc* are listed below: - ``0``: Do not emit a separate memory initialization file (default). Instead keep the static initialization inside the generated JavaScript as text. - ``1``: Emit a separate memory initialization file in binary format. This is more efficient than storing it as text inside JavaScript, but does mean you have another file to publish. The binary file will also be loaded asynchronously, which means ``main()`` will not be called until the file is downloaded and applied; you cannot call any C functions until it arrives. - .. note:: Call yourself from ``main()`` to know when all asynchronous processing has completed and it is safe to call library functions, as ``main()`` will only be called at that time. You can also call ``addOnPreMain`` from a ``preRun``. - + .. note:: The :ref:`safest way ` to ensure that it is safe to call C functions (the initialisation file has loaded) is to call a notifier function from ``main()``. You might also call ``addOnPreMain`` from a :js:attr:`Module.preRun`. + ``-Wno-warn-absolute-paths`` Suppress warnings about the use of absolute paths in ``-I`` and ``-L`` command line directives. This is used to hide the warnings and acknowledge that the explicit use of absolute paths is intentional. @@ -315,7 +316,9 @@ Options that are modified or new in *emcc* are listed below: .. note:: If ``--memory-init-file`` is used, then in addition to the **.js** or **.html** file which is generated, a **.mem** file will also be created. ``-c`` - Tells *gcc* not to run the linker and causes LLVM bitcode to be generated, as *emcc* only generates JavaScript in the final linking stage of building. + Tells *gcc* to generate LLVM bitcode (only). The linker is not run, and the final JavaScript executable is not produced. + + Environment variables ===================== From 4df83e7f812fa7836db11d4c8c5b18fcad7c9a36 Mon Sep 17 00:00:00 2001 From: Jukka Jylanki Date: Thu, 21 Aug 2014 13:02:30 +0300 Subject: [PATCH 09/60] Adjust clang version check to detect custom compiler vendor strings. #2698 --- tools/shared.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tools/shared.py b/tools/shared.py index f9394be51a0c8..3bb1db301b364 100644 --- a/tools/shared.py +++ b/tools/shared.py @@ -273,7 +273,8 @@ def new(*args): def get_clang_version(): global actual_clang_version if actual_clang_version is None: - actual_clang_version = Popen([CLANG, '-v'], stderr=PIPE).communicate()[1].split('\n')[0].split(' ')[2] + ver = Popen([CLANG, '-v'], stderr=PIPE).communicate()[1].split('\n')[0].split(' ') + actual_clang_version = ver[ver.index('version')+1] return actual_clang_version def check_clang_version(): From 424b709cac07c3735007b2c31c24caed5dcedc24 Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Thu, 21 Aug 2014 14:46:58 -0700 Subject: [PATCH 10/60] move alignment and type utilities out of Runtime, as not needed at runtime --- src/analyzer.js | 14 ++++++------- src/compiler.js | 4 +++- src/intertyper.js | 6 +++--- src/jsifier.js | 6 +++--- src/modules.js | 2 +- src/parseTools.js | 48 ++++++++++++++++++++++----------------------- src/runtime.js | 50 ++++++++++++++++++++++++----------------------- 7 files changed, 67 insertions(+), 63 deletions(-) diff --git a/src/analyzer.js b/src/analyzer.js index 73691937ef504..4380a76588a74 100644 --- a/src/analyzer.js +++ b/src/analyzer.js @@ -189,7 +189,7 @@ function analyzer(data, sidePass) { if (USE_TYPED_ARRAYS == 2) { function getLegalVars(base, bits, allowLegal) { bits = bits || 32; // things like pointers are all i32, but show up as 0 bits from getBits - if (allowLegal && bits <= 32) return [{ intertype: 'value', ident: base + ('i' + bits in Runtime.INT_TYPES ? '' : '$0'), bits: bits, type: 'i' + bits }]; + if (allowLegal && bits <= 32) return [{ intertype: 'value', ident: base + ('i' + bits in Compiletime.INT_TYPES ? '' : '$0'), bits: bits, type: 'i' + bits }]; if (isNumber(base)) return getLegalLiterals(base, bits); if (base[0] == '{') { warnOnce('seeing source of illegal data ' + base + ', likely an inline struct - assuming zeroinit'); @@ -641,8 +641,8 @@ function analyzer(data, sidePass) { case 'bitcast': { var inType = item.type2; var outType = item.type; - if ((inType in Runtime.INT_TYPES && outType in Runtime.FLOAT_TYPES) || - (inType in Runtime.FLOAT_TYPES && outType in Runtime.INT_TYPES)) { + if ((inType in Compiletime.INT_TYPES && outType in Compiletime.FLOAT_TYPES) || + (inType in Compiletime.FLOAT_TYPES && outType in Compiletime.INT_TYPES)) { i++; continue; // special case, handled in processMathop } @@ -948,7 +948,7 @@ function analyzer(data, sidePass) { if (type.length == 1) return; if (Types.types[type]) return; if (['internal', 'hidden', 'inbounds', 'void'].indexOf(type) != -1) return; - if (Runtime.isNumberType(type)) return; + if (Compiletime.isNumberType(type)) return; dprint('types', 'Adding type: ' + type); // 'blocks': [14 x %struct.X] etc. If this is a pointer, we need @@ -1264,7 +1264,7 @@ function analyzer(data, sidePass) { variable.impl = VAR_NATIVE; } else if (MICRO_OPTS && variable.origin === 'alloca' && !variable.hasValueTaken && variable.allocatedNum === 1 && - (Runtime.isNumberType(pointedType) || Runtime.isPointerType(pointedType))) { + (Compiletime.isNumberType(pointedType) || isPointerType(pointedType))) { // A pointer to a value which is only accessible through this pointer. Basically // a local value on the stack, which nothing fancy is done on. So we can // optimize away the pointing altogether, and just have a native variable @@ -1311,7 +1311,7 @@ function analyzer(data, sidePass) { func.lines.forEach(function(line, i) { if (line.intertype === 'load') { // Floats have no concept of signedness. Mark them as 'signed', which is the default, for which we do nothing - if (line.type in Runtime.FLOAT_TYPES) { + if (line.type in Compiletime.FLOAT_TYPES) { line.unsigned = false; return; } @@ -1681,7 +1681,7 @@ function analyzer(data, sidePass) { hasAlloca = true; if (USE_TYPED_ARRAYS === 2) { // We need to keep the stack aligned - item.allocatedSize = Runtime.forceAlign(item.allocatedSize, Runtime.STACK_ALIGN); + item.allocatedSize = RuntimeGenerator.forceAlign(item.allocatedSize, Runtime.STACK_ALIGN); } } var index = 0; diff --git a/src/compiler.js b/src/compiler.js index 2a98b129f44f2..3a0886fe39647 100644 --- a/src/compiler.js +++ b/src/compiler.js @@ -308,7 +308,7 @@ function compile(raw) { B = new Benchmarker(); -try { +//try { if (ll_file) { if (phase === 'glue') { compile(';'); @@ -318,6 +318,7 @@ try { compile(ll_file); // we are given raw .ll } } +/* } catch(err) { if (err.indexOf('Aborting compilation due to previous errors') != -1) { // Compiler failed on user error, print out the error message. @@ -343,6 +344,7 @@ try { }, 500); } else throw err; } +*/ //var M = keys(tokenCacheMisses).map(function(m) { return [m, misses[m]] }).sort(function(a, b) { return a[1] - b[1] }); //printErr(dump(M.slice(M.length-10))); diff --git a/src/intertyper.js b/src/intertyper.js index 323787acd3009..244eec696cc0d 100644 --- a/src/intertyper.js +++ b/src/intertyper.js @@ -417,7 +417,7 @@ function intertyper(lines, sidePass, baseLineNums) { } Types.needAnalysis[type] = 0; - if (Runtime.isNumberType(type) || pointingLevels(type) >= 1) { + if (Compiletime.isNumberType(type) || pointingLevels(type) >= 1) { return { value: toNiceIdent(value.text), type: type }; } else if (value.text in ZEROINIT_UNDEF) { // undef doesn't really need initting, but why not return { intertype: 'emptystruct', type: type }; @@ -464,7 +464,7 @@ function intertyper(lines, sidePass, baseLineNums) { if (item.tokens[0].text == 'type') { var fields = []; var packed = false; - if (Runtime.isNumberType(item.tokens[1].text)) { + if (Compiletime.isNumberType(item.tokens[1].text)) { // Clang sometimes has |= i32| instead of |= { i32 }| fields = [item.tokens[1].text]; } else if (item.tokens[1].text != 'opaque') { @@ -821,7 +821,7 @@ function intertyper(lines, sidePass, baseLineNums) { function allocaHandler(item) { item.intertype = 'alloca'; item.allocatedType = item.tokens[1].text; - if (item.tokens.length > 3 && Runtime.isNumberType(item.tokens[3].text)) { + if (item.tokens.length > 3 && Compiletime.isNumberType(item.tokens[3].text)) { item.ident = toNiceIdent(item.tokens[4].text); } else { item.ident = 1; diff --git a/src/jsifier.js b/src/jsifier.js index 0842d32cbee15..d9d9fd39e2040 100644 --- a/src/jsifier.js +++ b/src/jsifier.js @@ -207,7 +207,7 @@ function JSify(data, functionsOnly) { //dprint('jsifier const: ' + JSON.stringify(value) + ',' + type + '\n'); if (value.intertype in PARSABLE_LLVM_FUNCTIONS) { return [finalizeLLVMFunctionCall(value)]; - } else if (Runtime.isNumberType(type) || pointingLevels(type) >= 1) { + } else if (Compiletime.isNumberType(type) || pointingLevels(type) >= 1) { return [makeGlobalUse(indexizeFunctions(parseNumerical(value.value), type))]; } else if (value.intertype === 'emptystruct') { return makeEmptyStruct(type); @@ -282,7 +282,7 @@ function JSify(data, functionsOnly) { if (item.external) { if (LibraryManager.library[item.ident.slice(1)]) { constant = LibraryManager.library[item.ident.slice(1)]; - } else if (Runtime.isNumberType(item.type) || isPointerType(item.type)) { + } else if (Compiletime.isNumberType(item.type) || isPointerType(item.type)) { constant = zeros(Runtime.getNativeFieldSize(item.type)); } else { constant = makeEmptyStruct(item.type); @@ -1550,7 +1550,7 @@ function JSify(data, functionsOnly) { } else { var size = calcAllocatedSize(removeAllPointing(type)); ret = makeCopyValues(getFastValue('tempVarArgs', '+', offset), arg, size, null, null, varargsByVals[i], ','); - offset += Runtime.forceAlign(size, Runtime.STACK_ALIGN); + offset += RuntimeGenerator.forceAlign(size, Runtime.STACK_ALIGN); } return ret; }).filter(function(arg) { diff --git a/src/modules.js b/src/modules.js index 8adba58b5e443..fd7b212417b4c 100644 --- a/src/modules.js +++ b/src/modules.js @@ -279,7 +279,7 @@ var Functions = { for (var i = 0; i < argTypes.length; i++) { var type = argTypes[i]; if (!type) break; // varargs - if (type in Runtime.FLOAT_TYPES) { + if (type in Compiletime.FLOAT_TYPES) { sig += Functions.getSignatureLetter(type); } else { var chunks = getNumIntChunks(type); diff --git a/src/parseTools.js b/src/parseTools.js index c5c4384bda79d..cb912ece1d21a 100644 --- a/src/parseTools.js +++ b/src/parseTools.js @@ -148,7 +148,7 @@ function isStructPointerType(type) { // we must check later on, in call(), where we have more // context, to differentiate such cases. // A similar thing happens in isStructType() - return !Runtime.isNumberType(type) && type[0] == '%'; + return !Compiletime.isNumberType(type) && type[0] == '%'; } function isPointerType(type) { @@ -222,7 +222,7 @@ function getNumIntChunks(type) { } function isIdenticallyImplemented(type1, type2) { - var floats = +(type1 in Runtime.FLOAT_TYPES) + +(type2 in Runtime.FLOAT_TYPES); + var floats = +(type1 in Compiletime.FLOAT_TYPES) + +(type2 in Compiletime.FLOAT_TYPES); if (floats == 2) return true; if (floats == 1) return false; return getNumIntChunks(type1) == getNumIntChunks(type2); @@ -326,7 +326,7 @@ function getReturnType(type) { var isTypeCache = {}; // quite hot, optimize as much as possible function isType(type) { if (type in isTypeCache) return isTypeCache[type]; - var ret = isPointerType(type) || isVoidType(type) || Runtime.isNumberType(type) || isStructType(type) || isFunctionType(type); + var ret = isPointerType(type) || isVoidType(type) || Compiletime.isNumberType(type) || isStructType(type) || isFunctionType(type); isTypeCache[type] = ret; return ret; } @@ -338,7 +338,7 @@ function isVarArgsFunctionType(type) { } function getNumLegalizedVars(type) { // how many legalized variables are needed to represent this type - if (type in Runtime.FLOAT_TYPES) return 1; + if (type in Compiletime.FLOAT_TYPES) return 1; return Math.max(getNumIntChunks(type), 1); } @@ -1032,7 +1032,7 @@ function calcAllocatedSize(type) { // i32, 0, 0, 0 - for example, an int32 is here, then nothing to do for the 3 next bytes, naturally function generateStructTypes(type) { if (isArray(type)) return type; // already in the form of [type, type,...] - if (Runtime.isNumberType(type) || isPointerType(type)) { + if (Compiletime.isNumberType(type) || isPointerType(type)) { if (USE_TYPED_ARRAYS == 2 && type == 'i64') { return ['i64', 0, 0, 0, 'i32', 0, 0, 0]; } @@ -1051,7 +1051,7 @@ function generateStructTypes(type) { for (var i = 0; i < num; i++) { var type = array ? typeData.fields[0] : typeData.fields[i]; if (!SAFE_HEAP && isPointerType(type)) type = '*'; // do not include unneeded type names without safe heap - if (Runtime.isNumberType(type) || isPointerType(type)) { + if (Compiletime.isNumberType(type) || isPointerType(type)) { if (USE_TYPED_ARRAYS == 2 && type == 'i64') { ret[index++] = 'i64'; ret[index++] = 0; @@ -1065,7 +1065,7 @@ function generateStructTypes(type) { } ret[index++] = type; } else { - if (Runtime.isStructType(type) && type[1] === '0') { + if (isStructType(type) && type[1] === '0') { // this is [0 x something], which does nothing // XXX this happens in java_nbody... assert(i === typeData.fields.length-1); continue; @@ -1200,7 +1200,7 @@ function asmEnsureFloat(value, type) { // ensures that a float type has either 5 value = ensureDot(value); return 'Math_fround(' + value + ')'; } - if (type in Runtime.FLOAT_TYPES) { + if (type in Compiletime.FLOAT_TYPES) { return ensureDot(value); } else { return value; @@ -1208,7 +1208,7 @@ function asmEnsureFloat(value, type) { // ensures that a float type has either 5 } function asmInitializer(type) { - if (type in Runtime.FLOAT_TYPES) { + if (type in Compiletime.FLOAT_TYPES) { if (PRECISE_F32 && type === 'float') return 'Math_fround(0)'; return RUNNING_JS_OPTS ? '+0' : '.0'; } else { @@ -1220,7 +1220,7 @@ function asmCoercion(value, type, signedness) { if (!ASM_JS) return value; if (type == 'void') { return value; - } else if (type in Runtime.FLOAT_TYPES) { + } else if (type in Compiletime.FLOAT_TYPES) { if (isNumber(value)) { return asmEnsureFloat(value, type); } else { @@ -1327,7 +1327,7 @@ function makeGetValue(ptr, pos, type, noNeedFirst, unsigned, ignore, align, noSa if (printType !== 'null' && printType[0] !== '#') printType = '"' + safeQuote(printType) + '"'; if (printType[0] === '#') printType = printType.substr(1); if (ASM_JS) { - if (!ignore && phase !== 'funcs') return asmCoercion('SAFE_HEAP_LOAD(' + asmCoercion(offset, 'i32') + ', ' + Runtime.getNativeTypeSize(type) + ', ' + ((type in Runtime.FLOAT_TYPES)|0) + ', ' + (!!unsigned+0) + ')', type); + if (!ignore && phase !== 'funcs') return asmCoercion('SAFE_HEAP_LOAD(' + asmCoercion(offset, 'i32') + ', ' + Runtime.getNativeTypeSize(type) + ', ' + ((type in Compiletime.FLOAT_TYPES)|0) + ', ' + (!!unsigned+0) + ')', type); // else fall through } else { return asmCoercion('SAFE_HEAP_LOAD(' + offset + ', ' + (ASM_JS ? 0 : printType) + ', ' + (!!unsigned+0) + ', ' + ((!checkSafeHeap() || ignore)|0) + ')', type); @@ -1338,8 +1338,8 @@ function makeGetValue(ptr, pos, type, noNeedFirst, unsigned, ignore, align, noSa ret = asmCoercion(ret, type); } if (ASM_HEAP_LOG) { - ret = makeInlineCalculation('(asmPrint' + (type in Runtime.FLOAT_TYPES ? 'Float' : 'Int') + '(' + (asmPrintCounter++) + ',' + asmCoercion('VALUE', type) + '), VALUE)', ret, - 'temp' + (type in Runtime.FLOAT_TYPES ? 'Double' : 'Int')); + ret = makeInlineCalculation('(asmPrint' + (type in Compiletime.FLOAT_TYPES ? 'Float' : 'Int') + '(' + (asmPrintCounter++) + ',' + asmCoercion('VALUE', type) + '), VALUE)', ret, + 'temp' + (type in Compiletime.FLOAT_TYPES ? 'Double' : 'Int')); } return ret; } @@ -1439,7 +1439,7 @@ function makeSetValue(ptr, pos, value, type, noNeedFirst, ignore, align, noSafe, if (printType !== 'null' && printType[0] !== '#') printType = '"' + safeQuote(printType) + '"'; if (printType[0] === '#') printType = printType.substr(1); if (ASM_JS) { - if (!ignore && phase !== 'funcs') return asmCoercion('SAFE_HEAP_STORE(' + asmCoercion(offset, 'i32') + ', ' + asmCoercion(value, type) + ', ' + Runtime.getNativeTypeSize(type) + ', ' + ((type in Runtime.FLOAT_TYPES)|0) + ')', type); + if (!ignore && phase !== 'funcs') return asmCoercion('SAFE_HEAP_STORE(' + asmCoercion(offset, 'i32') + ', ' + asmCoercion(value, type) + ', ' + Runtime.getNativeTypeSize(type) + ', ' + ((type in Compiletime.FLOAT_TYPES)|0) + ')', type); // else fall through } else { return 'SAFE_HEAP_STORE(' + offset + ', ' + value + ', ' + (ASM_JS ? 0 : printType) + ', ' + ((!checkSafeHeap() || ignore)|0) + ')'; @@ -1610,7 +1610,7 @@ function getFastValue(a, op, b, type) { if (op === '*') { // We can't eliminate where a or b are 0 as that would break things for creating // a negative 0. - if ((aNumber === 0 || bNumber === 0) && !(type in Runtime.FLOAT_TYPES)) { + if ((aNumber === 0 || bNumber === 0) && !(type in Compiletime.FLOAT_TYPES)) { return '0'; } else if (aNumber === 1) { return b; @@ -1622,7 +1622,7 @@ function getFastValue(a, op, b, type) { return '(' + a + '<<' + shifts + ')'; } } - if (!(type in Runtime.FLOAT_TYPES)) { + if (!(type in Compiletime.FLOAT_TYPES)) { // if guaranteed small enough to not overflow into a double, do a normal multiply var bits = getBits(type) || 32; // default is 32-bit multiply for things like getelementptr indexes // Note that we can emit simple multiple in non-asm.js mode, but asm.js will not parse "16-bit" multiple, so must do imul there @@ -1632,7 +1632,7 @@ function getFastValue(a, op, b, type) { return '(Math_imul(' + a + ',' + b + ')|0)'; } } else if (op === '/') { - if (a === '0' && !(type in Runtime.FLOAT_TYPES)) { // careful on floats, since 0*NaN is not 0 + if (a === '0' && !(type in Compiletime.FLOAT_TYPES)) { // careful on floats, since 0*NaN is not 0 return '0'; } else if (b === 1) { return a; @@ -1801,9 +1801,9 @@ function makeGetSlabs(ptr, type, allowMultiple, unsigned) { if (!USE_TYPED_ARRAYS) { return ['HEAP']; } else if (USE_TYPED_ARRAYS == 1) { - if (type in Runtime.FLOAT_TYPES || type === 'int64') { // XXX should be i64, no? + if (type in Compiletime.FLOAT_TYPES || type === 'int64') { // XXX should be i64, no? return ['FHEAP']; // If USE_FHEAP is false, will fail at runtime. At compiletime we do need it for library stuff. - } else if (type in Runtime.INT_TYPES || isPointerType(type)) { + } else if (type in Compiletime.INT_TYPES || isPointerType(type)) { return [unsigned ? 'IHEAPU' : 'IHEAP']; } else { assert(allowMultiple, 'Unknown slab type and !allowMultiple: ' + type); @@ -2351,13 +2351,13 @@ function processMathop(item) { assert(USE_TYPED_ARRAYS == 2, 'Can only bitcast ints <-> floats with typed arrays mode 2'); var inType = item.params[0].type; var outType = item.type; - if (inType in Runtime.INT_TYPES && outType in Runtime.FLOAT_TYPES) { + if (inType in Compiletime.INT_TYPES && outType in Compiletime.FLOAT_TYPES) { if (legalizedI64s) { return '(' + makeSetTempDouble(0, 'i32', idents[0] + '$0') + ', ' + makeSetTempDouble(1, 'i32', idents[0] + '$1') + ', ' + makeGetTempDouble(0, 'double') + ')'; } else { return makeInlineCalculation(makeSetTempDouble(0, 'i32', 'VALUE[0]') + ',' + makeSetTempDouble(1, 'i32', 'VALUE[1]') + ',' + makeGetTempDouble(0, 'double'), idents[0], 'tempI64'); } - } else if (inType in Runtime.FLOAT_TYPES && outType in Runtime.INT_TYPES) { + } else if (inType in Compiletime.FLOAT_TYPES && outType in Compiletime.INT_TYPES) { if (legalizedI64s) { return makeSetTempDouble(0, 'double', idents[0]) + '; ' + finish([makeGetTempDouble(0, 'i32'), makeGetTempDouble(1, 'i32')]); } else { @@ -2537,10 +2537,10 @@ function processMathop(item) { // Most bitcasts are no-ops for us. However, the exception is int to float and float to int var inType = item.params[0].type; var outType = item.type; - if ((inType in Runtime.INT_TYPES && outType in Runtime.FLOAT_TYPES) || - (inType in Runtime.FLOAT_TYPES && outType in Runtime.INT_TYPES)) { + if ((inType in Compiletime.INT_TYPES && outType in Compiletime.FLOAT_TYPES) || + (inType in Compiletime.FLOAT_TYPES && outType in Compiletime.INT_TYPES)) { assert(USE_TYPED_ARRAYS == 2, 'Can only bitcast ints <-> floats with typed arrays mode 2'); - if (inType in Runtime.INT_TYPES) { + if (inType in Compiletime.INT_TYPES) { return '(' + makeSetTempDouble(0, 'i32', idents[0]) + ',' + makeGetTempDouble(0, 'float') + ')'; } else { return '(' + makeSetTempDouble(0, 'float', idents[0]) + ',' + makeGetTempDouble(0, 'i32') + ')'; diff --git a/src/runtime.js b/src/runtime.js index 44c36668dea7c..b86ba0bcfa8ab 100644 --- a/src/runtime.js +++ b/src/runtime.js @@ -71,11 +71,22 @@ var RuntimeGenerator = { return ret; }, + forceAlign: function(target, quantum) { + quantum = quantum || {{{ QUANTUM_SIZE }}}; + if (quantum == 1) return target; + if (isNumber(target) && isNumber(quantum)) { + return Math.ceil(target/quantum)*quantum; + } else if (isNumber(quantum) && isPowerOfTwo(quantum)) { + return '(((' +target + ')+' + (quantum-1) + ')&' + -quantum + ')'; + } + return 'Math.ceil((' + target + ')/' + quantum + ')*' + quantum; + }, + alignMemory: function(target, quantum) { if (typeof quantum !== 'number') { quantum = '(quantum ? quantum : {{{ STACK_ALIGN }}})'; } - return target + ' = ' + Runtime.forceAlign(target, quantum); + return target + ' = ' + RuntimeGenerator.forceAlign(target, quantum); }, // Given two 32-bit unsigned parts of an emulated 64-bit number, combine them into a JS number (double). @@ -95,6 +106,18 @@ function unInline(name_, params) { return ret; } +var Compiletime = { + isPointerType: isPointerType, + isStructType: isStructType, + + isNumberType: function(type) { + return type in Compiletime.INT_TYPES || type in Compiletime.FLOAT_TYPES; + }, + + INT_TYPES: set('i1', 'i8', 'i16', 'i32', 'i64'), + FLOAT_TYPES: set('float', 'double'), +}; + var Runtime = { // When a 64 bit long is returned from a compiled function the least significant // 32 bit word is passed in the return value, but the most significant 32 bit @@ -112,27 +135,6 @@ var Runtime = { STACKTOP = stackTop; }, - forceAlign: function(target, quantum) { - quantum = quantum || {{{ QUANTUM_SIZE }}}; - if (quantum == 1) return target; - if (isNumber(target) && isNumber(quantum)) { - return Math.ceil(target/quantum)*quantum; - } else if (isNumber(quantum) && isPowerOfTwo(quantum)) { - return '(((' +target + ')+' + (quantum-1) + ')&' + -quantum + ')'; - } - return 'Math.ceil((' + target + ')/' + quantum + ')*' + quantum; - }, - - isNumberType: function(type) { - return type in Runtime.INT_TYPES || type in Runtime.FLOAT_TYPES; - }, - - isPointerType: isPointerType, - isStructType: isStructType, - - INT_TYPES: set('i1', 'i8', 'i16', 'i32', 'i64'), - FLOAT_TYPES: set('float', 'double'), - // Imprecise bitops utilities or64: function(x, y) { var l = (x | 0) | (y | 0); @@ -216,10 +218,10 @@ var Runtime = { type.flatIndexes = type.fields.map(function(field) { index++; var size, alignSize; - if (Runtime.isNumberType(field) || Runtime.isPointerType(field)) { + if (Compiletime.isNumberType(field) || Compiletime.isPointerType(field)) { size = Runtime.getNativeTypeSize(field); // pack char; char; in structs, also char[X]s. alignSize = Runtime.getAlignSize(field, size); - } else if (Runtime.isStructType(field)) { + } else if (Compiletime.isStructType(field)) { if (field[1] === '0') { // this is [0 x something]. When inside another structure like here, it must be at the end, // and it adds no size From 8a5c20aaf55b6afbdca5c82c26f5f69a4de8fc7e Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Thu, 21 Aug 2014 14:47:40 -0700 Subject: [PATCH 11/60] add settings.js note of when we are running fastcomp --- emcc | 2 ++ src/settings.js | 1 + 2 files changed, 3 insertions(+) diff --git a/emcc b/emcc index 7cf67b75cc65e..67ddaeee6aa76 100755 --- a/emcc +++ b/emcc @@ -986,6 +986,8 @@ try: if js_opts: shared.Settings.RUNNING_JS_OPTS = 1 + shared.Settings.RUNNING_FASTCOMP = fastcomp + shared.Settings.EMSCRIPTEN_VERSION = shared.EMSCRIPTEN_VERSION shared.Settings.OPT_LEVEL = opt_level shared.Settings.DEBUG_LEVEL = debug_level diff --git a/src/settings.js b/src/settings.js index 59bc47f40ffad..42174ce9f9258 100644 --- a/src/settings.js +++ b/src/settings.js @@ -539,6 +539,7 @@ var NO_DYNAMIC_EXECUTION = 0; // When enabled, we do not emit eval() and new Fun // privileged firefox app, etc.) var RUNNING_JS_OPTS = 0; // whether js opts will be run, after the main compiler +var RUNNING_FASTCOMP = 1; // whether we are running the fastcomp backend var COMPILER_ASSERTIONS = 0; // costly (slow) compile-time assertions var COMPILER_FASTPATHS = 1; // use fast-paths to speed up compilation From cdb7dad8db02dffd252407e5f6c0a9e3509e7fc9 Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Thu, 21 Aug 2014 14:48:51 -0700 Subject: [PATCH 12/60] move imprecise bitops runtime utils into non-fastcomp --- src/runtime.js | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/runtime.js b/src/runtime.js index b86ba0bcfa8ab..370bc0df577f2 100644 --- a/src/runtime.js +++ b/src/runtime.js @@ -135,6 +135,7 @@ var Runtime = { STACKTOP = stackTop; }, +#if RUNNING_FASTCOMP == 0 // Imprecise bitops utilities or64: function(x, y) { var l = (x | 0) | (y | 0); @@ -151,6 +152,7 @@ var Runtime = { var h = (Math.round(x / 4294967296) ^ Math.round(y / 4294967296)) * 4294967296; return l + h; }, +#endif //! Returns the size of a type, as C/C++ would have it (in 32-bit), in bytes. //! @param type The type, by name. From 06c663933f73c496eff0e84a437d5dcd63f70397 Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Thu, 21 Aug 2014 14:56:34 -0700 Subject: [PATCH 13/60] clean up dedup and set appearance in runtime --- src/runtime.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/runtime.js b/src/runtime.js index 370bc0df577f2..31cea604041a8 100644 --- a/src/runtime.js +++ b/src/runtime.js @@ -189,9 +189,9 @@ var Runtime = { return Math.max(Runtime.getNativeTypeSize(type), Runtime.QUANTUM_SIZE); }, +#if RUNNING_FASTCOMP == 0 dedup: dedup, - - set: set, +#endif STACK_ALIGN: {{{ STACK_ALIGN }}}, From c6f531140114e3e0f6147ae0d3831619b79fb60e Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Thu, 21 Aug 2014 14:58:07 -0700 Subject: [PATCH 14/60] add structure alignment code to runtime only in non-fastcomp --- src/runtime.js | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/runtime.js b/src/runtime.js index 31cea604041a8..cbb82be874418 100644 --- a/src/runtime.js +++ b/src/runtime.js @@ -208,6 +208,7 @@ var Runtime = { return Math.min(size || (type ? Runtime.getNativeFieldSize(type) : 0), Runtime.QUANTUM_SIZE); }, +#if RUNNING_FASTCOMP == 0 // Calculate aligned size, just like C structs should be. TODO: Consider // requesting that compilation be done with #pragma pack(push) /n #pragma pack(1), // which would remove much of the complexity here. @@ -340,6 +341,7 @@ var Runtime = { } return ret; }, +#endif dynCall: function(sig, ptr, args) { if (args && args.length) { From 97e2a795a958a322fb4112ad85a58e6f9d103b8f Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Thu, 21 Aug 2014 16:45:19 -0700 Subject: [PATCH 15/60] add NO_FILESYSTEM and NO_BROWSER options, to reduce file size in cases where those functionalities are not necessary --- src/compiler.js | 4 ++++ src/library.js | 18 ++++++++++++++++++ src/modules.js | 28 +++++++++++++++++++--------- src/settings.js | 7 +++++++ tests/test_other.py | 25 +++++++++++++++++++++++++ 5 files changed, 73 insertions(+), 9 deletions(-) diff --git a/src/compiler.js b/src/compiler.js index 3a0886fe39647..9e062d6f0d096 100644 --- a/src/compiler.js +++ b/src/compiler.js @@ -180,6 +180,10 @@ RUNTIME_DEBUG = LIBRARY_DEBUG || GL_DEBUG; if (SAFE_HEAP) USE_BSS = 0; // must initialize heap for safe heap +if (NO_BROWSER) { + DEFAULT_LIBRARY_FUNCS_TO_INCLUDE = DEFAULT_LIBRARY_FUNCS_TO_INCLUDE.filter(function(func) { return func !== '$Browser' }); +} + // Settings sanity checks assert(!(USE_TYPED_ARRAYS === 2 && QUANTUM_SIZE !== 4), 'For USE_TYPED_ARRAYS == 2, must have normal QUANTUM_SIZE of 4'); diff --git a/src/library.js b/src/library.js index f656ec8877f2e..f31370855522e 100644 --- a/src/library.js +++ b/src/library.js @@ -2521,6 +2521,7 @@ LibraryManager.library = { }, puts__deps: ['fputs', 'fputc', 'stdout'], puts: function(s) { +#if NO_FILESYSTEM == 0 // int puts(const char *s); // http://pubs.opengroup.org/onlinepubs/000095399/functions/puts.html // NOTE: puts() always writes an extra newline. @@ -2532,6 +2533,14 @@ LibraryManager.library = { var newlineRet = _fputc({{{ charCode('\n') }}}, stdout); return (newlineRet < 0) ? -1 : ret + 1; } +#else + // extra effort to support puts, even without a filesystem. very partial, very hackish + var result = Pointer_stringify(s); + var string = result.substr(0); + if (string[string.length-1] === '\n') string = string.substr(0, string.length-1); // remove a final \n, as Module.print will do that + Module.print(string); + return result.length; +#endif }, fread__deps: ['$FS', 'read'], fread: function(ptr, size, nitems, stream) { @@ -2818,8 +2827,17 @@ LibraryManager.library = { printf: function(format, varargs) { // int printf(const char *restrict format, ...); // http://pubs.opengroup.org/onlinepubs/000095399/functions/printf.html +#if NO_FILESYSTEM == 0 var stdout = {{{ makeGetValue(makeGlobalUse('_stdout'), '0', 'void*') }}}; return _fprintf(stdout, format, varargs); +#else + // extra effort to support printf, even without a filesystem. very partial, very hackish + var result = __formatString(format, varargs); + var string = intArrayToString(result); + if (string[string.length-1] === '\n') string = string.substr(0, string.length-1); // remove a final \n, as Module.print will do that + Module.print(string); + return result.length; +#endif }, dprintf__deps: ['_formatString', 'write'], dprintf: function(fd, format, varargs) { diff --git a/src/modules.js b/src/modules.js index fd7b212417b4c..3db6663c02bdd 100644 --- a/src/modules.js +++ b/src/modules.js @@ -427,14 +427,24 @@ var LibraryManager = { var libraries = [ 'library.js', - 'library_path.js', - 'library_fs.js', - 'library_idbfs.js', - 'library_memfs.js', - 'library_nodefs.js', - 'library_sockfs.js', - 'library_tty.js', - 'library_browser.js', + ]; + if (!NO_FILESYSTEM) { + libraries = libraries.concat([ + 'library_path.js', + 'library_fs.js', + 'library_idbfs.js', + 'library_memfs.js', + 'library_nodefs.js', + 'library_sockfs.js', + 'library_tty.js', + ]); + } + if (!NO_BROWSER) { + libraries = libraries.concat([ + 'library_browser.js', + ]); + } + libraries = libraries.concat([ 'library_sdl.js', 'library_gl.js', 'library_glut.js', @@ -449,7 +459,7 @@ var LibraryManager = { 'library_html5.js', 'library_signals.js', 'library_async.js' - ].concat(additionalLibraries); + ]).concat(additionalLibraries); for (var i = 0; i < libraries.length; i++) { var filename = libraries[i]; diff --git a/src/settings.js b/src/settings.js index 42174ce9f9258..16f68c959da3f 100644 --- a/src/settings.js +++ b/src/settings.js @@ -346,6 +346,13 @@ var MEMFS_APPEND_TO_TYPED_ARRAYS = 0; // If set to nonzero, MEMFS will always ut // for appending data to files. The default behavior is to use typed arrays for files // when the file size doesn't change after initial creation, and for files that do // change size, use normal JS arrays instead. +var NO_FILESYSTEM = 0; // If set, does not build in any filesystem support. Useful if you are just doing pure + // computation, but not reading files or using any streams (including fprintf, and other + // stdio.h things) or anything related. The one exception is there is partial support for printf, + // and puts, hackishly. +var NO_BROWSER = 0; // If set, disables building in browser support using the Browser object. Useful if you are + // just doing pure computation in a library, and don't need any browser capabilities like a main loop + // (emscripten_set_main_loop), or setTimeout, etc. var USE_BSS = 1; // https://en.wikipedia.org/wiki/.bss // When enabled, 0-initialized globals are sorted to the end of the globals list, diff --git a/tests/test_other.py b/tests/test_other.py index 5c8ec7a3827b7..45fd7f2c0e32a 100644 --- a/tests/test_other.py +++ b/tests/test_other.py @@ -3977,6 +3977,31 @@ def get_size(name): test([]) test(['-O1']) + def test_no_nuthin(self): + def test(opts, ratio): + print opts + def get_size(name): + return os.stat(name).st_size + sizes = {} + def do(name, moar_opts): + Popen([PYTHON, EMCC, path_from_root('tests', 'hello_world.c'), '-o', name + '.js'] + opts + moar_opts).communicate() + sizes[name] = get_size(name + '.js') + self.assertContained('hello, world!', run_js(name + '.js')) + do('normal', []) + do('no_fs', ['-s', 'NO_FILESYSTEM=1']) + do('no_browser', ['-s', 'NO_BROWSER=1']) + do('no_nuthin', ['-s', 'NO_FILESYSTEM=1', '-s', 'NO_BROWSER=1']) + print ' ', sizes + assert sizes['no_fs'] < sizes['normal'] + assert sizes['no_browser'] < sizes['normal'] + assert sizes['no_nuthin'] < sizes['no_fs'] + assert sizes['no_nuthin'] < sizes['no_browser'] + assert sizes['no_nuthin'] < ratio*sizes['normal'] + test([], 0.66) + test(['-O1'], 0.66) + test(['-O2'], 0.50) + test(['-O3', '--closure', '1'], 0.60) + def test_stat_fail_alongtheway(self): open('src.cpp', 'w').write(r''' #include From 6dc95a7a382bf08039c52bb9ff36fda1d42d06b0 Mon Sep 17 00:00:00 2001 From: hamishwillee Date: Fri, 22 Aug 2014 09:48:27 +1000 Subject: [PATCH 16/60] Fixes to home page layout, size of inline code text, emcc final updates, improvements to tutorial and downloads --- .../emscripten_sphinx_rtd_theme/layout.html | 1 + .../static/css/theme.css | 17 ++- site/source/docs/getting_started/FAQ.rst | 2 + site/source/docs/getting_started/Tutorial.rst | 104 ++++++++---------- .../source/docs/getting_started/downloads.rst | 28 +++-- ...ing_started_with_emscripten_and_vs2010.rst | 22 +++- site/source/docs/getting_started/index.rst | 7 +- .../about_emscripten.rst | 2 +- .../docs/introducing_emscripten/index.rst | 8 +- site/source/docs/site/about.rst | 21 ++-- site/source/docs/tools_reference/emcc.rst | 3 +- site/source/docs/tools_reference/emsdk.rst | 2 +- site/source/home_page_layout.html | 6 +- site/source/index.rst | 14 +-- 14 files changed, 138 insertions(+), 99 deletions(-) diff --git a/site/source/_themes/emscripten_sphinx_rtd_theme/layout.html b/site/source/_themes/emscripten_sphinx_rtd_theme/layout.html index 2315ad930aaaf..5c25cb145b04e 100644 --- a/site/source/_themes/emscripten_sphinx_rtd_theme/layout.html +++ b/site/source/_themes/emscripten_sphinx_rtd_theme/layout.html @@ -98,6 +98,7 @@ {% set toctree = toctree(maxdepth=4, collapse=False, includehidden=True) %} {% if toctree %} {{ toctree }} + Index {% else %}
{{ toc }}
diff --git a/site/source/_themes/emscripten_sphinx_rtd_theme/static/css/theme.css b/site/source/_themes/emscripten_sphinx_rtd_theme/static/css/theme.css index 8775c04111263..fc6431dc9d294 100644 --- a/site/source/_themes/emscripten_sphinx_rtd_theme/static/css/theme.css +++ b/site/source/_themes/emscripten_sphinx_rtd_theme/static/css/theme.css @@ -37,7 +37,22 @@ body{ background:#edf0f2 } -.wy-text-left{text-align:left}.wy-text-center{text-align:center}.wy-text-right{text-align:right}.wy-text-large{font-size:120%}.wy-text-normal{font-size:100%}.wy-text-small,small{font-size:80%}.wy-text-strike{text-decoration:line-through}.wy-text-warning{color:#e67e22 !important}a.wy-text-warning:hover{color:#eb9950 !important}.wy-text-info{color:#2980b9 !important}a.wy-text-info:hover{color:#409ad5 !important}.wy-text-success{color:#27ae60 !important}a.wy-text-success:hover{color:#36d278 !important}.wy-text-danger{color:#e74c3c !important}a.wy-text-danger:hover{color:#ed7669 !important}.wy-text-neutral{color:#404040 !important}a.wy-text-neutral:hover{color:#595959 !important}h1,h2,h3,h4,h5,h6,legend{margin-top:0;font-weight:700;font-family:"Roboto Slab","ff-tisa-web-pro","Georgia",Arial,sans-serif}p{line-height:24px;margin:0;font-size:16px;margin-bottom:24px}h1{font-size:175%}h2{font-size:150%}h3{font-size:125%}h4{font-size:115%}h5{font-size:110%}h6{font-size:100%}code,.rst-content tt{white-space:nowrap;max-width:100%;background:#fff;border:solid 1px #e1e4e5;font-size:75%;padding:0 5px;font-family:"Inconsolata","Consolata","Monaco",monospace;color:#e74c3c;overflow-x:auto}code.code-large,.rst-content tt.code-large{font-size:90%}.wy-plain-list-disc,.rst-content .section ul,.rst-content .toctree-wrapper ul,article ul{list-style:disc;line-height:24px;margin-bottom:24px} +.wy-text-left{text-align:left}.wy-text-center{text-align:center}.wy-text-right{text-align:right}.wy-text-large{font-size:120%}.wy-text-normal{font-size:100%}.wy-text-small,small{font-size:80%}.wy-text-strike{text-decoration:line-through}.wy-text-warning{color:#e67e22 !important}a.wy-text-warning:hover{color:#eb9950 !important}.wy-text-info{color:#2980b9 !important}a.wy-text-info:hover{color:#409ad5 !important}.wy-text-success{color:#27ae60 !important}a.wy-text-success:hover{color:#36d278 !important}.wy-text-danger{color:#e74c3c !important}a.wy-text-danger:hover{color:#ed7669 !important}.wy-text-neutral{color:#404040 !important}a.wy-text-neutral:hover{color:#595959 !important}h1,h2,h3,h4,h5,h6,legend{margin-top:0;font-weight:700;font-family:"Roboto Slab","ff-tisa-web-pro","Georgia",Arial,sans-serif}p{line-height:24px;margin:0;font-size:16px;margin-bottom:24px}h1{font-size:175%}h2{font-size:150%}h3{font-size:125%}h4{font-size:115%}h5{font-size:110%}h6{font-size:100%} + +code, .rst-content tt + { + white-space:nowrap; + max-width:100%; + background:#fff; + border:solid 1px #e1e4e5; + /* font-size:75%; */ + font-size:90%; + padding:0 5px; + font-family:"Inconsolata","Consolata","Monaco",monospace;color:#e74c3c; + overflow-x:auto + } + +code.code-large,.rst-content tt.code-large{font-size:90%}.wy-plain-list-disc,.rst-content .section ul,.rst-content .toctree-wrapper ul,article ul{list-style:disc;line-height:24px;margin-bottom:24px} .wy-plain-list-disc li,.rst-content .section ul li,.rst-content .toctree-wrapper ul li,article ul li { list-style:disc;margin-left:24px} diff --git a/site/source/docs/getting_started/FAQ.rst b/site/source/docs/getting_started/FAQ.rst index 5046ed0b8901f..43588b5aa83c8 100644 --- a/site/source/docs/getting_started/FAQ.rst +++ b/site/source/docs/getting_started/FAQ.rst @@ -173,6 +173,8 @@ FAQ (wiki-import) **A.** This is a limitation of the le32 frontend in clang. You can use the x86 frontend instead by compiling with ``EMCC_LLVM_TARGET=i386-pc-linux-gnu`` in the environment (however you will lose the advantages of le32 which includes better alignment of doubles). +.. _faq-when-safe-to-call-compiled-functions: + - **Q.** I am building a library, and sometimes I get an error when I call a compiled function before the page fully loaded. How can I tell when is safe to call it? **A.** The easiest way to find out when loading is complete (which is asynchronous, as it often requires loading files, such as the .mem file or preloade files), is to just add a ``main()`` function. It will be called when it is safe to do so, after startup is complete, so that is a signal that it is safe to call any compiled method. diff --git a/site/source/docs/getting_started/Tutorial.rst b/site/source/docs/getting_started/Tutorial.rst index 0a32173d14e63..a65eb01800512 100644 --- a/site/source/docs/getting_started/Tutorial.rst +++ b/site/source/docs/getting_started/Tutorial.rst @@ -1,32 +1,30 @@ .. _Tutorial: -============================================ -Emscripten Tutorial (under-construction) -============================================ - -**Using Emscripten is, at a base level, fairly simple. This tutorial takes you through the steps needed to compile your first Emscripten examples from the command line. It also shows how to preload files and set the compiler optimization flags.** +====================================== +Emscripten Tutorial (ready-for-review) +====================================== -.. note:: We don't cover it in this tutorial, but Emscripten is also integrated with Microsoft Visual Studio 2010. +**Using Emscripten is, at a base level, fairly simple. This tutorial takes you through the steps needed to compile your first Emscripten examples from the command line. It also shows how to work with files and set the main compiler optimization flags.** - The :term:`vs-tool` plugin is automatically deployed by the :term:`Windows NSIS Installer Emscripten SDK` if *Visual Studio 2010* is present on your system. This adds an 'Emscripten' configuration to the list of available Solution Configurations in Visual Studio. Activate this configuration for a solution/project to make Visual Studio run the project build through Emscripten, producing **.html** or **.js** output depending on the configured project properties. +.. tip:: Check out :ref:`this topic ` if you want to use *Emscripten* with Microsoft *Visual Studio 2010*. First things first ====================== -Make sure you have :ref:`downloaded and installed ` Emscripten (the exact approach for doing this will depend your operating system: Windows, Mac or Linux). +Make sure you have :ref:`downloaded and installed ` Emscripten (the exact approach for doing this will depend your operating system: Linux, Windows, or Mac). -Emscripten is accessed using the :ref:`emcc `. This script invokes all the other tools needed to build your code, and can act as a drop-in replacement for a standard compiler like *gcc*. It is called on the command line using ``emcc`` or ``em++`` +Emscripten is accessed using the :ref:`emccdoc`. This script invokes all the other tools needed to build your code, and can act as a drop-in replacement for a standard compiler like *gcc*. It is called on the command line using ``./emcc`` or ``./em++``. -.. note:: On Mac OS X the tool is called using the slightly different syntax: ``./emcc`` or ``./em++`` (or even directly via Python: ``python emcc``). The remainder of this tutorial uses the Windows syntax (``emcc``). +.. note:: On Windows the tool is called using the slightly different syntax: ``emcc`` or ``em++``. The remainder of this tutorial uses the Linux approach (``./emcc``). For the next section you will need to open a command prompt: - On Linux or Mac OS X, open a *Terminal*. - On Windows open the :ref:`Emscripten Command Prompt `, a command prompt that has been pre-configured with the correct system paths and settings to point to the :term:`active ` Emscripten tools. To access this prompt, type **Emscripten** in the Windows 8 start screen, and then select the **Emscripten Command Prompt** option. -Navigate with the command prompt to the :term:`SDK root directory` for your target SDK. This is an SDK-version-specific folder below the :term:`emsdk root directory`, e.g.: **\\emscripten\\1.20.0\\**. +Navigate with the command prompt to the :term:`SDK root directory` for your target SDK. This is an SDK-version-specific folder below the :term:`emsdk root directory`: **/emscripten/1.20.0/**. -.. warning:: Emscripten test code must be built from the "SDK Root" above (some of the code is dependent on file locations, and will build but not run if compiled from another location). +.. note:: The tests should be compiled from the "SDK Root" directory. This is required because some tests load files, and the locations of these files within Emscripten's virtual file system root is relative to the current directory at build time. Verifying Emscripten @@ -34,33 +32,32 @@ Verifying Emscripten If you haven't run Emscripten before, run it now with: :: - emcc -v + ./emcc -v If the output contains warnings about missing tools, see :ref:`verifying-the-emscripten-environment` for debugging help. Otherwise continue to the next sections where we'll build some code. Running Emscripten -====================================== +================== -You can now compile your first C++ file to JavaScript! +You can now compile your first C++ file to JavaScript. First, lets have a look at the file to be compiled: **hello_world.cpp**. This is the simplest test code in the SDK, and as you can see, all it does is print "hello, world!" to the console and then exit. .. include:: ../../../../tests/hello_world.cpp :literal: - -To build the JavaScript version of this code we simply specify the C++ file after *emcc*: :: +To build the JavaScript version of this code, simply specify the C++ file after *emcc*: :: - emcc tests/hello_world.cpp + ./emcc tests/hello_world.cpp There should now be an **a.out.js** file in the current directory. Run it using :term:`node.js`: :: - node a.out.js + ./node a.out.js This prints "hello, world!" to the console, as expected. @@ -68,19 +65,18 @@ This prints "hello, world!" to the console, as expected. - Generating HTML -====================================== +=============== -Emscripten can also generate HTML for testing embedded JavaScript. To generate HTML, use the ``-o`` (output) command and specify an html file as the target file: :: +Emscripten can also generate HTML for testing embedded JavaScript. To generate HTML, use the ``-o`` (:ref:`output `) command and specify an html file as the target file: :: - emcc tests/hello_world.cpp -o hello.html + ./emcc tests/hello_world.cpp -o hello.html Open the web page in a web browser. As you can see, the framework defines a text area for displaying the output of the ``printf()`` calls in the native code. -The HTML isn't limited just to just displaying text. You can also use the SDL API to show a colored cube in a Canvas element (on browsers that support it). For an example, build the **hello_world_sdl.cpp** test code and then refresh the browser: :: +The HTML output isn't limited just to just displaying text. You can also use the SDL API to show a colored cube in a Canvas element (on browsers that support it). For an example, build the `hello_world_sdl.cpp `_ test code and then refresh the browser: :: - emcc tests/hello_world_sdl.cpp -o hello.html + ./emcc tests/hello_world_sdl.cpp -o hello.html The source code for the second example is given below: @@ -89,15 +85,15 @@ The source code for the second example is given below: Using files -====================================== +=========== -Your C/C++ code can access files using the normal libc API (stdio: ``fopen``, etc.). +.. note:: Your C/C++ code can access files using the normal libc stdio API (``fopen``, ``fclose``, etc.) -JavaScript is usually run in the sandboxed environment of a web browser, without direct access to the local filesystem. Emscripten simulates a file system which you can access from the compiled code using the normal libc API. Files that you want to access should be :ref:`preloaded ` or :ref:`embedded ` into the virtual file system. +JavaScript is usually run in the sandboxed environment of a web browser, without direct access to the local file system. Emscripten simulates a file system which you can access from your compiled C/C++ code using the normal libc stdio API. -Preloading generates a virtual filesystem that corresponds to the filesystem structure at *compile* time, relative to the current directory. +Files that you want to access should be :ref:`preloaded ` or :ref:`embedded ` into the virtual file system. Preloading (or embedding) generates a virtual file system that corresponds to the file system structure at *compile* time, *relative to the current directory*. -.. todo:: **HamishW** When filesystem guide updated may be a better link for preloading and embedding than the emcc links above. These might even be better as term links in glossary. +.. todo:: **HamishW** When filesystem guide updated may be a better link for preloading and embedding than the *emcc* links above. These might even be better as term links in glossary. The `hello_world_file.cpp `_ example shows how to load a file (both the test code and the file to be loaded shown below): @@ -107,7 +103,11 @@ The `hello_world_file.cpp `_. We compile the example from the directory "above" **tests** to ensure that the text file is stored at this location in the virtual filesystem. +.. note:: The example expects to be able to load a file located at **tests/hello_world_file.txt**: :: + + FILE *file = fopen("tests/hello_world_file.txt", "rb"); + + We compile the example from the directory "above" **tests** to ensure that virtual filesystem is created with the correct structure relative to the compile-time directory. The following command is used to preload the data file. The ``--preload-file`` option will automatically preload the file before running the compiled code. This is useful because loading data from the network cannot be done synchronously in browsers outside Web Workers. :: @@ -118,36 +118,23 @@ Open ``hello.html`` in the *Firefox web browser* to see the data from **hello_wo .. note:: Unfortunately *Chrome* and *Internet Explorer* do not support ``file://`` :term:`XHR` requests, and can't directly load the local file in which preloaded data is stored. For these browsers you'll need to serve the files using a webserver. The easiest way to do this is to use the python **SimpleHTTPServer** (in the current directory do ``python -m SimpleHTTPServer 8080`` and then open ``localhost:8080/hello.html``). ----- - -For an example of how to load files with SDL, check out `tests/hello_image_sdl.c `_: - -.. include:: ../../../../tests/hello_image_sdl.c - :literal: - -The source code expects a file **screenshot.jpg** in the current directory. As discussed above, this means that we need to compile the source and preload from the same directory that contains the screenshot. Change to the **tests/** directory and run: :: - - emcc hello_image_sdl.c --preload-file screenshot.jpg -o a.html - -Then browse to **a.html** (again, noting that you will need to use either Mozilla Firefox or a web server). You should see a pretty cool image displayed. - For more information about working with the file system see the :ref:`Filesystem-Guide`, :ref:`Filesystem-API` and :ref:`Synchronous-virtual-XHR-backed-file-system-usage`. Optimizing code -====================================== +=============== -Emscripten, like *gcc*, generates unoptimized code by default. You can generate slightly-optimized code with the ``-O1`` command line argument (run the test code from the :term:`SDK root directory`): :: +Emscripten, like *gcc*, generates unoptimized code by default. You can generate :ref:`slightly-optimized ` code with the ``-O1`` command line argument (run the test code from the :term:`SDK root directory`): :: - emcc -O1 tests/hello_world.cpp + ./emcc -O1 tests/hello_world.cpp The "hello world" code created in **a.out.js** doesn't really need to be optimized, so you won't see a difference in speed when compared to the unoptimized version. However, you can compare the generated code to see the differences. ``-O1`` applies several minor optimizations and removes some runtime assertions. For example, ``printf`` will have been replaced by ``puts`` in the generated code. -The optimizations provided by ``-O2`` are much more aggressive. If you run the following command and inspect the generated code (**a.out.js**) you will see that it looks very different: :: +The optimizations provided by ``-O2`` (see :ref:`here `) are much more aggressive. If you run the following command and inspect the generated code (**a.out.js**) you will see that it looks very different: :: - emcc -O2 tests/hello_world.cpp + ./emcc -O2 tests/hello_world.cpp For more information about compiler optimization options see :ref:`Optimizing-Code` and the :ref:`emcc tool reference `. @@ -155,19 +142,19 @@ For more information about compiler optimization options see :ref:`Optimizing-Co .. _running-emscripten-tests: Running the Emscripten Test Suite and Benchmarks -============================================================================ +================================================ Emscripten has an extensive test suite at `tests/runner.py `_. To run every test (this may take several hours), simply call the test script: :: python tests/runner.py -The individual tests are listed in the different test suites - for example "test_hello_world" is defined in the `core test suite here `_. You can run individual tests as shown: :: +The individual tests are listed in the different test suites — for example "test_hello_world" is defined in the `core test suite here `_. You can run individual tests as shown: :: python tests/runner.py test_hello_world .. todo:: **HamishW** Confirm that this is how test suites are done. We really should have a stand alone topic for this and link to it at this point. -To view the generated code from that individual test, you can first set ``EMCC_DEBUG=1``. This is shown for both Windows and Linxu below: :: +To view the generated code from that individual test, you can first set ``EMCC_DEBUG=1``: :: # On Windows, use "set" to set and un-set the environment variable: set EMCC_DEBUG=1 @@ -190,7 +177,7 @@ Note that **Node.js** cannot run all of the tests in the suite; if you care abou .. _running-emscripten-benchmarks: -To run the Emscripten benchmark tests, enter the following command: :: +To run the Emscripten *benchmark* tests, enter the following command: :: python tests/runner.py benchmark @@ -199,11 +186,12 @@ This will compile a sequence of benchmarks and run them several times, reporting General tips and next steps -====================================== +=========================== This tutorial walked you through your first steps in calling Emscripten from the command line. There is, of course, far more you can do with the tool. Below are other general tips for using Emscripten: -- This site has lots more information about :ref:`compiling and building projects `, :ref:`integrating your native code with the web environment `, :ref:`packaging your code ` and publishing. -- The Emscripten test suite is a great place to look for examples of how to use Emscripten. For example, if you want to better understand how the *emcc* ``--pre-js`` option works, search for ``--pre-js`` in the test suite: the test suite is extensive and there are likely to be at least some examples. -- To learn how to use Emscripten in advanced ways, read :ref:`src/settings.js ` and :ref:`emcc ` which describe the compiler options, and :ref:`emscripten-h` which describes JavaScript-specific C APIs that your C/C++ programs can use when compiled with Emscripten. -- When in doubt, :ref:`get in touch `! +- This site has lots more information about :ref:`compiling and building projects `, :ref:`integrating your native code with the web environment `, :ref:`packaging your code ` and publishing. +- The Emscripten test suite is a great place to look for examples of how to use Emscripten. For example, if you want to better understand how the *emcc* ``--pre-js`` option works, search for ``--pre-js`` in the test suite: the test suite is extensive and there are likely to be at least some examples. +- To learn how to use Emscripten in advanced ways, read :ref:`src/settings.js ` and :ref:`emcc ` which describe the compiler options, and :ref:`emscripten-h` which describes JavaScript-specific C APIs that your C/C++ programs can use when compiled with Emscripten. +- Read the :ref:`FAQ`. +- When in doubt, :ref:`get in touch `! diff --git a/site/source/docs/getting_started/downloads.rst b/site/source/docs/getting_started/downloads.rst index 3ba51b89ad757..27085239dd816 100644 --- a/site/source/docs/getting_started/downloads.rst +++ b/site/source/docs/getting_started/downloads.rst @@ -64,10 +64,10 @@ The *Portable Emscripten SDK* is a no-installer version of the SDK package. It i First check the :ref:`Platform-specific notes ` below and install any prerequisites. -Install the SDK using the following steps: +Install or update the SDK using the following steps: 1. Download and unzip the portable SDK package to a directory of your choice. This directory will contain the Emscripten SDK. -#. Open a command prompt inside the SDK directory and run the following :ref:`emsdk ` commands to get the latest SDK tools and set them as :term:`active `. +#. Open a command prompt inside the SDK directory and run the following :ref:`emsdk ` commands to get the latest tools from Github and set them as :term:`active `. .. note:: On Windows, invoke the tool with **emsdk** instead of **./emsdk**: @@ -80,13 +80,20 @@ Install the SDK using the following steps: ./emsdk install latest # Make the "latest" SDK "active" - ./emsdk activate latest - -Whenever you change the location of the Portable SDK (e.g. take it to another computer), re-run the final command: ``./emsdk activate latest``. - -.. tip:: The instructions above can also be used to get new SDKs, as they are released. + ./emsdk activate latest +#. **Linux and Mac OS X only:** Call ``source ./emsdk_env.sh`` after ``activate`` to set the system path to the active version of Emscripten: + :: + + # Set the current Emscripten path on Linux/Mac OS X + source ./emsdk_env.sh + + This step is not required on Windows because calling the ``activate`` command also sets the correct system path (this is not possible on Linux due to security restrictions). + +Whenever you change the location of the Portable SDK (e.g. take it to another computer), re-run the ``./emsdk activate latest`` command (and ``source ./emsdk_env.sh`` for Linux). + + .. _platform-notes-installation_instructions-portable-SDK: Platform-specific notes @@ -112,7 +119,9 @@ Mac OS X Linux ++++++++ -.. note:: Pre-built binaries of tools are not available on Linux. Installing a tool will automatically clone and build that tool from the sources inside the **emsdk** directory. *Emsdk* does not interact with Linux package managers on the behalf of the user, nor does it install any tools to the system. All file changes are done inside the **emsdk/** directory. +**Pre-built binaries of tools are not available on Linux.** Installing a tool will automatically clone and build that tool from the sources inside the **emsdk** directory. + +.. note:: *Emsdk* does not install any tools to the system, or otherwise interact with Linux package managers. All file changes are done inside the **emsdk/** directory. - The system must have a working :ref:`compiler-toolchain` (because *emsdk* builds software from the source): @@ -171,6 +180,9 @@ Type the following (omitting comments) on the :ref:`Emscripten Command Prompt ` (or even your own fork). Check out all the possibilities in the :ref:`emsdk_howto`. diff --git a/site/source/docs/getting_started/getting_started_with_emscripten_and_vs2010.rst b/site/source/docs/getting_started/getting_started_with_emscripten_and_vs2010.rst index f3818c9c4a5d9..6ce6f56d29daa 100644 --- a/site/source/docs/getting_started/getting_started_with_emscripten_and_vs2010.rst +++ b/site/source/docs/getting_started/getting_started_with_emscripten_and_vs2010.rst @@ -4,8 +4,27 @@ Getting started using Emscripten from the Visual Studio 2010 IDE (under-construction) =========================================================================================== +Windows Developers who want to use an IDE can develop and compile their Emscripten projects from `Microsoft Visual Studio 2010 `_. This article shows you how. -To build a Visual Studio solution using the Emscripten toolchain, select the "Emscripten" configuration from the Configuration Manager dropdown as the active configuration, and choose Build Solution (F7). +.. note:: Visual Studio 2011 and 2012 are not supported. + +Integrating Emscripten and Visual Studio +======================================== + +The integration is enabled the :term:`vs-tool` plugin. + +This plugin is automatically deployed by the :term:`Windows NSIS Installer Emscripten SDK` if *Visual Studio 2010* is present on your system. It is also possible to :ref:`manually integrate Emscripten into Visual Studio 2010 `. + +The *vs-tool* plugin adds an 'Emscripten' configuration to the list of available *Solution Configurations* in Visual Studio. Activate this configuration for a solution/project to make Visual Studio run the project build through Emscripten, producing **.html** or **.js** output depending on the configured project properties. + +How to build a Visual Studio solution using Emscripten +================================================================================ + +First select the "Emscripten" configuration from the Configuration Manager dropdown as the active configuration, and choose Build Solution (F7). + + +How to launch a project in a web browser from Visual Studio +================================================================================ To launch a project directly to a web browser from Visual Studio, right-click on the project to run, choose "Set as Startup Project", and select Start without Debugging (Ctrl+F5). This should launch the generated .html file to the browser you specified in EMCC\_WEBBROWSER\_EXE. A bug(?) in Visual Studio causes a "Executable for Debug Session" dialog to occasionally open up when you hit Ctrl+F5. This can be ignored by clicking Yes, then No, or simply by hitting Esc and then tapping Ctrl+F5 again. @@ -17,3 +36,4 @@ Empty. After this, you can switch between building the solution for Win32 and Em When you want to create a new Visual Studio project for Emscripten, we recommend you start with a Visual C++ Empty Project. This will create a new project for the Win32 platform. Then convert that project for Emscripten as outlined in the previous paragraph. + diff --git a/site/source/docs/getting_started/index.rst b/site/source/docs/getting_started/index.rst index bcf71b4b17b28..6b579725afc7c 100644 --- a/site/source/docs/getting_started/index.rst +++ b/site/source/docs/getting_started/index.rst @@ -1,9 +1,14 @@ .. _getting-started-index: ===================================== -Getting Started (under-construction) +Getting Started (ready-for-review) ===================================== +Now you know why Emscripten is :ref:`right for you `, it's time to *get started*. + +This section provides a walk-through of :ref:`downloading and installing the SDK ` and the basics of :ref:`using the Emscripten toolchain `. The general :ref:`FAQ` answers many common questions about setting up and using Emscripten. + +We also explain where to :ref:`Report Bugs ` in the toolchain and the site, and how to use Emscripten with :ref:`Visual Studio 2010 ` (Windows only). .. toctree:: :maxdepth: 1 diff --git a/site/source/docs/introducing_emscripten/about_emscripten.rst b/site/source/docs/introducing_emscripten/about_emscripten.rst index d7fc0cc9f1ef4..d8361830fb5fb 100644 --- a/site/source/docs/introducing_emscripten/about_emscripten.rst +++ b/site/source/docs/introducing_emscripten/about_emscripten.rst @@ -54,7 +54,7 @@ The :ref:`emsdk` is used to manage multiple SDKs and tools, and to specify the p A number of other tools are not shown — for example, Java can optionally be used by *emcc* to run the :term:`closure compiler`, which can further decrease code size. -The whole toolchain is delivered in the :ref:`Emscripten SDK ` +The whole toolchain is delivered in the :ref:`Emscripten SDK `, and can be used on Linux, Windows or Mac OS X. Porting code to use Emscripten diff --git a/site/source/docs/introducing_emscripten/index.rst b/site/source/docs/introducing_emscripten/index.rst index 557cdc1699a53..e95c658861a15 100644 --- a/site/source/docs/introducing_emscripten/index.rst +++ b/site/source/docs/introducing_emscripten/index.rst @@ -1,8 +1,8 @@ -================================================= -Introducing Emscripten (under-construction) -================================================= +========================================= +Introducing Emscripten (ready-for-review) +========================================= -This section introduces Emscripten. It explains what the tool does, why it is needed, its limitations and its licensing. After reading, you will understand whether Emscripten is the right tool for you, and where to go if you have :ref:`further questions `. +This section explains what the Emscripten does, why it is needed, its limitations and its licensing. After reading, you will understand whether Emscripten is the right tool for you, and where to go if you have :ref:`further questions `. .. toctree:: :maxdepth: 1 diff --git a/site/source/docs/site/about.rst b/site/source/docs/site/about.rst index 41e7c3967c89f..3ab58e14b7b5c 100644 --- a/site/source/docs/site/about.rst +++ b/site/source/docs/site/about.rst @@ -28,11 +28,6 @@ By the end of the project all articles should be published and all of this page .. todo:: **HamishW** Delete this whole section at the end of the project. At that point there should only be HamishW markup for possible Todos. Note the search link immediately above too - this is to the kripken site and may need to change if the site moves. -Reporting bugs -============== - -Please :ref:`report documentation bugs ` as you would any other Emscripten bug. Help :ref:`fix them ` by updating existing documents or by creating new ones. - Searching the site ================== @@ -41,7 +36,19 @@ Searching returns only topics which contain **all** the specified keywords. .. tip:: Always start by searching for *single* words like "interacting" or "compiling". Generally this will be enough to find the relevant document. If not, you can refine the search by adding additional terms. -Note that searches that include characters like "-" and "+" will not work. There is no support for logical operators. +.. note:: Searches that include characters like "-" and "+" will not work. There is no support for logical operators. + +Reporting bugs +============== + +Please :ref:`report documentation bugs ` as you would any other Emscripten bug. Help :ref:`fix them ` by updating existing documents or by creating new ones. + +Contributing to the site +======================== + +:ref:`Contributions ` to this site (and indeed any part of Emscripten) are welcome! + +Check out the rest of this article for instructions on how to :ref:`build the site ` and :ref:`write and update articles `. .. _building-the-site: @@ -49,7 +56,7 @@ Note that searches that include characters like "-" and "+" will not work. There Building the site ================== -The site sources are in the Emscripten *incoming* branch, `site `_ directory. Changes should be committed to the incoming branch. +The site sources are stored on Github `here `_. Edits and additions should be submitted to this branch in the same way as any other change to the tool. The site is published to the **kripken/emscripten-site** *gh-pages* branch (Github pages). diff --git a/site/source/docs/tools_reference/emcc.rst b/site/source/docs/tools_reference/emcc.rst index 585910c85f002..8b3031c54e43b 100644 --- a/site/source/docs/tools_reference/emcc.rst +++ b/site/source/docs/tools_reference/emcc.rst @@ -277,7 +277,7 @@ Options that are modified or new in *emcc* are listed below: - ``0``: Do not emit a separate memory initialization file (default). Instead keep the static initialization inside the generated JavaScript as text. - ``1``: Emit a separate memory initialization file in binary format. This is more efficient than storing it as text inside JavaScript, but does mean you have another file to publish. The binary file will also be loaded asynchronously, which means ``main()`` will not be called until the file is downloaded and applied; you cannot call any C functions until it arrives. - .. note:: The :ref:`safest way ` to ensure that it is safe to call C functions (the initialisation file has loaded) is to call a notifier function from ``main()``. You might also call ``addOnPreMain`` from a :js:attr:`Module.preRun`. + .. note:: The :ref:`safest way ` to ensure that it is safe to call C functions (the initialisation file has loaded) is to call a notifier function from ``main()``. ``-Wno-warn-absolute-paths`` Suppress warnings about the use of absolute paths in ``-I`` and ``-L`` command line directives. This is used to hide the warnings and acknowledge that the explicit use of absolute paths is intentional. @@ -304,6 +304,7 @@ Options that are modified or new in *emcc* are listed below: ``--valid_abspath path`` Whitelist an absolute path to prevent warnings about absolute include paths. +.. _emcc-o-target: ``-o `` The ``target`` file name extension defines what type of output be generated: diff --git a/site/source/docs/tools_reference/emsdk.rst b/site/source/docs/tools_reference/emsdk.rst index ab411cf87ce08..11fed04b62a71 100644 --- a/site/source/docs/tools_reference/emsdk.rst +++ b/site/source/docs/tools_reference/emsdk.rst @@ -200,7 +200,7 @@ Toggle between different tools and SDK versions using the :term:`activate Emscripten is an LLVM-based project that compiles C/C++ into h
-
+
Porting

Compile your existing projects written in C or C++ and run them on all modern browsers.

-
+
APIs

Emscripten converts OpenGL into WebGL, and lets you use familiar APIs like SDL, or HTML5 directly.

-
+
Fast

Thanks to LLVM optimizations and Emscripten's JavaScript-specific optimizations, code runs at near-native speed.

diff --git a/site/source/index.rst b/site/source/index.rst index 027e7a301325b..73d37ee310cb1 100644 --- a/site/source/index.rst +++ b/site/source/index.rst @@ -34,16 +34,4 @@ News docs/tools_reference/index docs/site/about - - - - -.. COMMENTS Scratchpad - This DOC Contents - .. contents:: Table of Contents - :ref:`genindex` **HamishW** This needs to be added to the sidebar - This page not yet designed. Thought is to include: - * Introduction - * Quickstart Signpost - with prominent link to "Getting Started" Tutorial - * Signposts for: News, Top Demos, Contributing, Github Project - * (Possibly) Signposts to: Twitter feed, Github issues (new, resolved) + \ No newline at end of file From e83ec61a80420cbe3ae2c79203af50b8574d4cf5 Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Thu, 21 Aug 2014 17:12:27 -0700 Subject: [PATCH 17/60] update docs for -c --- site/source/docs/tools_reference/emcc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/source/docs/tools_reference/emcc.rst b/site/source/docs/tools_reference/emcc.rst index 8b3031c54e43b..6a44fcb9fb4e7 100644 --- a/site/source/docs/tools_reference/emcc.rst +++ b/site/source/docs/tools_reference/emcc.rst @@ -317,7 +317,7 @@ Options that are modified or new in *emcc* are listed below: .. note:: If ``--memory-init-file`` is used, then in addition to the **.js** or **.html** file which is generated, a **.mem** file will also be created. ``-c`` - Tells *gcc* to generate LLVM bitcode (only). The linker is not run, and the final JavaScript executable is not produced. + Tells *emcc* to generate LLVM bitcode (which can then be linked with other bitcode files), instead of compiling all the way to JavaScript. From 435cfe7090c7be077ab9a99fd322c4a0fa9c851d Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Thu, 21 Aug 2014 17:12:47 -0700 Subject: [PATCH 18/60] update text docs --- site/build/text/docs/tools_reference/emcc.txt | 22 ++++++++----------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/site/build/text/docs/tools_reference/emcc.txt b/site/build/text/docs/tools_reference/emcc.txt index a409d173a7aee..0d181f6ae3ad6 100644 --- a/site/build/text/docs/tools_reference/emcc.txt +++ b/site/build/text/docs/tools_reference/emcc.txt @@ -1,6 +1,6 @@ -Emscripten Compiler Frontend (emcc) (under-construction) -******************************************************** +Emscripten Compiler Frontend (emcc) (ready-for-review) +****************************************************** **This document provides the command syntax for the Emscription Compiler Frontend.** @@ -23,9 +23,6 @@ The input file(s) can be either source code files that *Clang* can handle (C or C++), LLVM bitcode in binary form, or LLVM assembly files in human-readable form. -Supported targets include: llvm bitcode, JavaScript, NOT elf (autoconf -likes to see elf above to enable shared object support). - Arguments --------- @@ -284,7 +281,7 @@ Options that are modified or new in *emcc* are listed below: "--exclude-file " Files and directories to be excluded from *--embed-file* and - *--preload-file*. Wildcard is supported. + *--preload-file*. Wildcards (*) are supported. "--shell-file " The path name to a skeleton HTML file used when generating HTML @@ -420,10 +417,9 @@ Options that are modified or new in *emcc* are listed below: means "main()" will not be called until the file is downloaded and applied; you cannot call any C functions until it arrives. - Note: Call yourself from "main()" to know when all asynchronous - processing has completed and it is safe to call library - functions, as "main()" will only be called at that time. You can - also call "addOnPreMain" from a "preRun". + Note: The *safest way* to ensure that it is safe to call + C functions (the initialisation file has loaded) is to + call a notifier function from "main()". "-Wno-warn-absolute-paths" Suppress warnings about the use of absolute paths in "-I" and "-L" @@ -482,9 +478,9 @@ Options that are modified or new in *emcc* are listed below: will also be created. "-c" - Tells *gcc* not to run the linker and causes LLVM bitcode to be - generated, as *emcc* only generates JavaScript in the final linking - stage of building. + Tells *emcc* to generate LLVM bitcode (which can then be linked + with other bitcode files), instead of compiling all the way to + JavaScript. Environment variables From 95cd41b47a57486bd338c35d7ce9dd7a21f1d9e7 Mon Sep 17 00:00:00 2001 From: hamishwillee Date: Fri, 22 Aug 2014 10:33:12 +1000 Subject: [PATCH 19/60] Add external link icon to all external links --- .../emscripten_sphinx_rtd_theme/footer.html | 2 +- .../emscripten_sphinx_rtd_theme/layout.html | 2 +- .../static/css/theme.css | 24 ++++++++++++------- 3 files changed, 18 insertions(+), 10 deletions(-) diff --git a/site/source/_themes/emscripten_sphinx_rtd_theme/footer.html b/site/source/_themes/emscripten_sphinx_rtd_theme/footer.html index 56a463c508b2d..51d542c44759b 100644 --- a/site/source/_themes/emscripten_sphinx_rtd_theme/footer.html +++ b/site/source/_themes/emscripten_sphinx_rtd_theme/footer.html @@ -41,7 +41,7 @@ {%- if hasdoc(document) %} {{ shorttext }}{{ longtext }} {%- elif document | truncate(4, True, end='') == 'http' %} - {{ shorttext }}{{ longtext }} + {{ shorttext }}{{ longtext }} {%- else %} {{ shorttext }} {%- endif %} diff --git a/site/source/_themes/emscripten_sphinx_rtd_theme/layout.html b/site/source/_themes/emscripten_sphinx_rtd_theme/layout.html index 5c25cb145b04e..04b3b419928f2 100644 --- a/site/source/_themes/emscripten_sphinx_rtd_theme/layout.html +++ b/site/source/_themes/emscripten_sphinx_rtd_theme/layout.html @@ -145,7 +145,7 @@ {%- if hasdoc(document) %} {{ shorttext }}{{ longtext }} {%- elif document | truncate(4, True, end='') == 'http' %} - {{ shorttext }}{{ longtext }} + {{ shorttext }}{{ longtext }} {%- endif %} {% endfor %} diff --git a/site/source/_themes/emscripten_sphinx_rtd_theme/static/css/theme.css b/site/source/_themes/emscripten_sphinx_rtd_theme/static/css/theme.css index fc6431dc9d294..394f0a8760ad2 100644 --- a/site/source/_themes/emscripten_sphinx_rtd_theme/static/css/theme.css +++ b/site/source/_themes/emscripten_sphinx_rtd_theme/static/css/theme.css @@ -1,7 +1,9 @@ *{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}article,aside,details,figcaption,figure,footer,header,hgroup,nav,section{display:block}audio,canvas,video{display:inline-block;*display:inline;*zoom:1}audio:not([controls]){display:none}[hidden]{display:none}*{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}html{font-size:100%;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%} body{margin:0}a:hover,a:active{outline:0}abbr[title]{border-bottom:1px dotted}b,strong{font-weight:bold}blockquote{margin:0}dfn{font-style:italic}hr{display:block;height:1px;border:0;border-top:1px solid #ccc;margin:20px 0;padding:0}ins{background:#ff9;color:#000;text-decoration:none}mark{background:#ff0;color:#000;font-style:italic;font-weight:bold}pre,code,.rst-content tt,kbd,samp{font-family:monospace,serif;_font-family:"courier new",monospace;font-size:1em}pre{white-space:pre}q{quotes:none}q:before,q:after{content:"";content:none}small{font-size:85%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sup{top:-0.5em}sub{bottom:-0.25em}ul,ol,dl{margin:0;padding:0;list-style:none;list-style-image:none}li{list-style:none}dd{margin:0}img{border:0;-ms-interpolation-mode:bicubic;vertical-align:middle;max-width:100%}svg:not(:root){overflow:hidden}figure{margin:0}form{margin:0}fieldset{border:0;margin:0;padding:0}label{cursor:pointer}legend{border:0;*margin-left:-7px;padding:0;white-space:normal}button,input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}button,input{line-height:normal}button,input[type="button"],input[type="reset"],input[type="submit"]{cursor:pointer;-webkit-appearance:button;*overflow:visible}button[disabled],input[disabled]{cursor:default}input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0;*width:13px;*height:13px}input[type="search"]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}input[type="search"]::-webkit-search-decoration,input[type="search"]::-webkit-search-cancel-button{-webkit-appearance:none}button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}textarea{overflow:auto;vertical-align:top;resize:vertical} -table{border-collapse:collapse;border-spacing:0}td{vertical-align:top}.chromeframe{margin:0.2em 0;background:#ccc;color:#000;padding:0.2em 0}.ir{display:block;border:0;text-indent:-999em;overflow:hidden;background-color:transparent;background-repeat:no-repeat;text-align:left;direction:ltr;*line-height:0}.ir br{display:none}.hidden{display:none !important;visibility:hidden}.visuallyhidden{border:0;clip:rect(0 0 0 0);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;width:1px}.visuallyhidden.focusable:active,.visuallyhidden.focusable:focus{clip:auto;height:auto;margin:0;overflow:visible;position:static;width:auto}.invisible{visibility:hidden}.relative{position:relative}big,small{font-size:100%}@media print{html,body,section{background:none !important}*{box-shadow:none !important;text-shadow:none !important;filter:none !important;-ms-filter:none !important}a,a:visited{text-decoration:underline}.ir a:after,a[href^="javascript:"]:after,a[href^="#"]:after{content:""}pre,blockquote{page-break-inside:avoid}thead{display:table-header-group}tr,img{page-break-inside:avoid}img{max-width:100% !important}@page{margin:0.5cm}p,h2,h3{orphans:3;widows:3}h2,h3{page-break-after:avoid}} +table{border-collapse:collapse;border-spacing:0}td{vertical-align:top}.chromeframe{margin:0.2em 0;background:#ccc;color:#000;padding:0.2em 0}.ir{display:block;border:0;text-indent:-999em;overflow:hidden;background-color:transparent;background-repeat:no-repeat;text-align:left;direction:ltr;*line-height:0}.ir br{display:none}.hidden{display:none !important;visibility:hidden}.visuallyhidden{border:0;clip:rect(0 0 0 0);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;width:1px}.visuallyhidden.focusable:active,.visuallyhidden.focusable:focus{clip:auto;height:auto;margin:0;overflow:visible;position:static;width:auto}.invisible{visibility:hidden}.relative{position:relative}big,small{font-size:100%}@media print{html,body,section{background:none !important}*{box-shadow:none !important;text-shadow:none !important;filter:none !important;-ms-filter:none !important}a,a:visited{text-decoration:underline} +.ir a:after,a[href^="javascript:"]:after,a[href^="#"]:after{content:""} +pre,blockquote{page-break-inside:avoid}thead{display:table-header-group}tr,img{page-break-inside:avoid}img{max-width:100% !important}@page{margin:0.5cm}p,h2,h3{orphans:3;widows:3}h2,h3{page-break-after:avoid}} .fa:before,.rst-content .admonition-title:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content dl dt .headerlink:before,.icon:before,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-alert,.rst-content .note,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .tip,.rst-content .warning,.rst-content .seealso,.btn,input[type="text"],input[type="password"],input[type="email"],input[type="url"],input[type="date"],input[type="month"],input[type="time"],input[type="datetime"],input[type="datetime-local"],input[type="week"],input[type="number"],input[type="search"],input[type="tel"],input[type="color"],select,textarea,.wy-menu-vertical li.on a,.wy-menu-vertical li.current>a,.wy-side-nav-search>a,.wy-side-nav-search .wy-dropdown>a,.wy-nav-top a{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1} .clearfix:before,.clearfix:after{display:table;content:""}.clearfix:after{clear:both}/*! * Font Awesome 4.0.3 by @davegandy - http://fontawesome.io - @fontawesome @@ -378,13 +380,19 @@ table.wrap-table-content td, table.wrap-table-content th { -/* HamishW - fix bullet lists inside arabic decimal lists not rendering properly */ -/* .wy-plain-list-decimal li, .rst-content .section ol li, .rst-content ol.arabic li, article ol li -.wy-plain-list-decimal ul .simple li { - list-style:disc; - margin-left:24px - } - */ +/* HamishW - add clear markup for external links */ + +a.external:after { + content: ""; + display: inline-block; + background-image: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAwAAAAMCAYAAABWdVznAAAAV0lEQVR4Xq2QwQ2AAAwC3cmd2Kk7sRP64CEJ9qOX8OPatMc/QKppnEPhTmJh23CLiwAqIw21CybKQ28qQi37WGFYBJcwfJQpP8LlEHKyZMF0IdmF13zlAjZ/6H4wb+mUAAAAAElFTkSuQmCC); + background-repeat: no-repeat; + background-position: right top; + background-origin: border-box; + width: 12px; + height: 16px; +} + /* HamishW - some CSS for the breadcrumb (make elements inline blocks) */ From e6148f29c39761a3199a2fe1b398c408c25c3a34 Mon Sep 17 00:00:00 2001 From: hamishwillee Date: Fri, 22 Aug 2014 10:37:22 +1000 Subject: [PATCH 20/60] partial update to V22010 getting started file --- .../getting_started_with_emscripten_and_vs2010.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/site/source/docs/getting_started/getting_started_with_emscripten_and_vs2010.rst b/site/source/docs/getting_started/getting_started_with_emscripten_and_vs2010.rst index 6ce6f56d29daa..c958c2cba5ca0 100644 --- a/site/source/docs/getting_started/getting_started_with_emscripten_and_vs2010.rst +++ b/site/source/docs/getting_started/getting_started_with_emscripten_and_vs2010.rst @@ -37,3 +37,4 @@ Empty. After this, you can switch between building the solution for Win32 and Em When you want to create a new Visual Studio project for Emscripten, we recommend you start with a Visual C++ Empty Project. This will create a new project for the Win32 platform. Then convert that project for Emscripten as outlined in the previous paragraph. + \ No newline at end of file From e0ac40123c38801f2c0112b9d96afd11c35e914a Mon Sep 17 00:00:00 2001 From: hamishwillee Date: Fri, 22 Aug 2014 12:15:26 +1000 Subject: [PATCH 21/60] changes to support SDK builds (both the actual text, and instructions on how to enable changes when needed) --- site/source/conf.py | 9 ++++-- site/source/docs/site/about.rst | 55 ++++++++++++++++++++++++++++----- site/source/index.rst | 10 +++++- 3 files changed, 62 insertions(+), 12 deletions(-) diff --git a/site/source/conf.py b/site/source/conf.py index 29d2fa9fb48ae..0875078cb0309 100644 --- a/site/source/conf.py +++ b/site/source/conf.py @@ -90,9 +90,9 @@ # built documents. # # The short X.Y version. -version = '1.20' +version = '1.23' # The full version, including alpha/beta/rc tags. -release = '1.20.0' +release = '1.23.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -395,4 +395,7 @@ # HamishW - tell Breathe about projects. Breathe is tool to convert Doxygen to Python objects, for import into Sphinx. #breathe_projects = { "myproject": "/home/me/docproj/doxyxml/", "nutshell":"./headers/xml/", } # HamishW - Specify a default project: -#breathe_default_project = "nutshell" \ No newline at end of file +#breathe_default_project = "nutshell" + +# Comment/uncomment the line below for normal/SDK builds. +#tags.add('sdkbuild') \ No newline at end of file diff --git a/site/source/docs/site/about.rst b/site/source/docs/site/about.rst index 3ab58e14b7b5c..644f07b2ce683 100644 --- a/site/source/docs/site/about.rst +++ b/site/source/docs/site/about.rst @@ -60,14 +60,7 @@ The site sources are stored on Github `here ` has a clear notification that it is an SDK build. + +SDK builds are enabled by adding the ``sdkbuild`` tag in `conf.py `_: :: + + #The line below must be uncommented for SDK builds. + tags.add('sdkbuild') + + +.. note:: In theory it should be possible to supply the ``sdkbuild`` tag as a command line option as shown below. However this is not working: + + :: + + make html SPHINXOPTS="-t sdkbuild" + + +.. _about-build-versions: + +Build version +------------- + +The documentation version should match the Emscripten version for the current build. For a general site build this will be the latest tagged release as defined in `Emscripten version `_. For an SDK build it will be the Emscripten version for the SDK. + +The version and release information is used in a few places in the documentation, for example :ref:`emscripten-authors`. +The version is set in `conf.py `_ in the ``version`` and ``release`` values. For example: :: + # The short X.Y version. + version = '1.23' + # The full version, including alpha/beta/rc tags. + release = '1.23.0' .. _writing-and-updating-articles: diff --git a/site/source/index.rst b/site/source/index.rst index 73d37ee310cb1..96110efa3769b 100644 --- a/site/source/index.rst +++ b/site/source/index.rst @@ -1,9 +1,18 @@ +.. _home-page: + .. Emscripten documentation master file, created by sphinx-quickstart on Tue Jul 01 09:20:29 2014. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +.. only:: sdkbuild + + .. admonition:: Welcome to Emscripten SDK |release| + + This documentation contains everything you need to :ref:`start developing ` with the Emscripten SDK. + .. warning:: This site is still under construction. + .. raw:: html :file: home_page_layout.html @@ -34,4 +43,3 @@ News docs/tools_reference/index docs/site/about - \ No newline at end of file From 00a0eb735c0bd249790f6db5c792ecf480588e03 Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Thu, 21 Aug 2014 17:22:56 -0700 Subject: [PATCH 22/60] module.html edits --- site/source/docs/api_reference/module.rst | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/site/source/docs/api_reference/module.rst b/site/source/docs/api_reference/module.rst index a618968d39786..c39065c663df5 100644 --- a/site/source/docs/api_reference/module.rst +++ b/site/source/docs/api_reference/module.rst @@ -6,7 +6,7 @@ Module object (ready-for-review) ``Module`` is a global JavaScript object, with attributes that Emscripten-generated code calls at various points in its execution. -Developers provide an implementation of ``Module`` to control the execution of code. For example, to define how notification messages from Emscripten are displayed, developers implement the :js:attr:`Module.print` attribute. +Developers can provide an implementation of ``Module`` to control the execution of code. For example, to define how notification messages from Emscripten are displayed, developers implement the :js:attr:`Module.print` attribute. .. note:: ``Module`` is also used to provide access functions (see :js:func:`ccall`) in a way that avoids issues with function name minification at higher optimisation levels. These functions are documented as part of their own APIs. @@ -22,18 +22,22 @@ Creating Module Use :ref:`emcc's ` ``--pre-js`` option to add JavaScript code that defines (or extends) the ``Module`` object with the behaviour you need. -When generating only JavaScript, no ``Module`` object is created by default, and the behaviour is entirely defined by the developer. For example, creating a ``Module`` object with the following code will cause all notifications from the program to be calls to ``alert()``. +When generating only JavaScript (as opposed to HTML), no ``Module`` object is created by default, and the behaviour is entirely defined by the developer. For example, creating a ``Module`` object with the following code will cause all notifications from the program to be calls to ``alert()``. :: var Module = { - 'print': function(text) { alert(text) } + 'print': function(text) { alert('stdout: ' + text) } + 'printErr': function(text) { alert('stderr: ' + text) } }; -.. important:: If you run closure compiler on your code (which is done by default in optimisation level :ref:`-02 ` and higher), you will need quotation marks around the properties of ``Module`` as in the example above (and you need to run closure on the compiled code together with the declaration of ``Module``). +.. important:: If you run closure compiler on your code (which is optional, and can be done by ``--closure 1``), you will need quotation marks around the properties of ``Module`` as in the example above (and you need to run closure on the compiled code together with the declaration of ``Module``, which is done automatically for a ``-pre-js`` file). -When generating HTML, Emscripten creates a ``Module`` object with default methods (see `src/shell.html `_). In this case you should again use ``--pre-js``, but this time to add properties to the existing ``Module`` object. +When generating HTML, Emscripten creates a ``Module`` object with default methods (see `src/shell.html `_). In this case you should again use ``--pre-js``, but this time to add properties to the existing ``Module`` object, for example + :: + + Module['print'] = function(text) { alert('stdout: ' + text) }; Affecting execution @@ -44,8 +48,11 @@ The following ``Module`` attributes affect code execution. .. js:attribute:: Module.print - Called when something is printed to standard output. + Called when something is printed to standard output (stdout) +.. js:attribute:: Module.printErr + + Called when something is printed to standard error (stderr) .. js:attribute:: Module.arguments @@ -72,7 +79,7 @@ The following ``Module`` attributes affect code execution. .. js:attribute:: Module.noExitRuntime - If set to ``true``, the runtime is not shut down after ``run`` completes. Shutting down the runtime calls shutdown callbacks, for example ``atexit`` calls. If you want to be able to continue to use the code after ``run()`` finishes, it is safer to set this. + If set to ``true``, the runtime is not shut down after ``run`` completes. Shutting down the runtime calls shutdown callbacks, for example ``atexit`` calls. If you want to be able to continue to use the code after ``run()`` finishes, it is necessary to set this. This is automatically set for you if you use an API command that implies that you want the runtime to not be shut down, for example ``emscripten_set_main_loop``. From ae14052569cf4ee8012ef16541e18f305c00a72a Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Fri, 22 Aug 2014 11:23:12 -0700 Subject: [PATCH 23/60] copy mem init file to temp dir, so EMCC_DEBUG intermediate files work in the temp dir --- emcc | 4 +--- tools/shared.py | 9 +++++++++ 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/emcc b/emcc index 67ddaeee6aa76..305d3a28e8108 100755 --- a/emcc +++ b/emcc @@ -1290,9 +1290,7 @@ try: open(memfile, 'wb').write(''.join(map(lambda x: chr(int(x or '0')), s.split(',')))) if DEBUG: # Copy into temp dir as well, so can be run there too - temp_memfile = os.path.join(shared.EMSCRIPTEN_TEMP_DIR, os.path.basename(memfile)) - if os.path.abspath(memfile) != os.path.abspath(memfile): - shutil.copyfile(memfile, temp_memfile) + shared.safe_copy(memfile, os.path.join(shared.EMSCRIPTEN_TEMP_DIR, os.path.basename(memfile))) return 'var memoryInitializer = "%s";' % os.path.basename(memfile) src = re.sub(shared.JS.memory_initializer_pattern, repl, open(final).read(), count=1) open(final + '.mem.js', 'w').write(src) diff --git a/tools/shared.py b/tools/shared.py index 3bb1db301b364..1c1511c2c68c4 100644 --- a/tools/shared.py +++ b/tools/shared.py @@ -1947,5 +1947,14 @@ def safe_move(src, dst): return shutil.move(src, dst) +def safe_copy(src, dst): + src = os.path.abspath(src) + dst = os.path.abspath(dst) + if os.path.isdir(dst): + dst = os.path.join(dst, os.path.basename(src)) + if src == dst: + return + shutil.copyfile(src, dst) + import js_optimizer From 919556db48740ba33ecc9fd2656a468bcf2d56c7 Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Fri, 22 Aug 2014 13:07:02 -0700 Subject: [PATCH 24/60] add --closure 2 option, to run closure even on the asm.js output --- emcc | 24 +++++++--- emscripten.py | 47 ++++++++++++++----- site/build/text/docs/tools_reference/emcc.txt | 15 ++++-- site/source/docs/tools_reference/emcc.rst | 5 +- tests/test_other.py | 13 +++-- 5 files changed, 72 insertions(+), 32 deletions(-) diff --git a/emcc b/emcc index 305d3a28e8108..65c9906088f31 100755 --- a/emcc +++ b/emcc @@ -920,8 +920,11 @@ try: assert not (shared.Settings.NO_DYNAMIC_EXECUTION and closure), 'cannot have both NO_DYNAMIC_EXECUTION and closure compiler enabled at the same time' if closure: - shared.Settings.CLOSURE_COMPILER = 1 + shared.Settings.CLOSURE_COMPILER = closure assert os.path.exists(shared.CLOSURE_COMPILER), logging.error('fatal: Closure compiler (%s) does not exist', shared.CLOSURE_COMPILER) + if closure == 2 and shared.Settings.ASM_JS == 1: + logging.warning('not all asm.js optimizations are possible with --closure 2, disabling those') + shared.Settings.ASM_JS = 2 assert shared.LLVM_TARGET in shared.COMPILER_OPTS if shared.LLVM_TARGET == 'i386-pc-linux-gnu': @@ -1352,7 +1355,7 @@ try: js_optimizer_extra_info = {} if opt_level >= 1 and js_opts: - logging.debug('running pre-closure post-opts') + logging.debug('running js post-opts') if DEBUG == '2': # Clean up the syntax a bit @@ -1399,28 +1402,37 @@ try: js_optimizer_queue += ['outline'] js_optimizer_extra_info['sizeToOutline'] = shared.Settings.OUTLINING_LIMIT - if opt_level >= 2 and (not closure or shared.Settings.ASM_JS) and shared.Settings.RELOOP and debug_level < 3: + if opt_level >= 2 and (not closure or shared.Settings.ASM_JS or closure == 2) and shared.Settings.RELOOP and debug_level < 3: if shared.Settings.ASM_JS and opt_level >= 3: js_optimizer_queue += ['registerizeHarder'] else: js_optimizer_queue += ['registerize'] if opt_level >= 2: - if debug_level < 2 and shared.Settings.ASM_JS: + if debug_level < 2 and shared.Settings.ASM_JS and not closure == 2: js_optimizer_queue += ['minifyNames'] if emit_symbol_map: js_optimizer_queue += ['symbolMap='+target+'.symbols'] if debug_level == 0: js_optimizer_queue += ['minifyWhitespace'] if shared.Settings.ASM_JS: - if closure: + if closure == 1: js_optimizer_queue += ['closure'] - elif debug_level <= 2 and not shared.Settings.MAIN_MODULE and not shared.Settings.SIDE_MODULE: + elif debug_level <= 2 and not shared.Settings.MAIN_MODULE and not shared.Settings.SIDE_MODULE and not closure: js_optimizer_queue += ['cleanup'] if not shared.Settings.SIDE_MODULE: js_optimizer_queue += ['last'] # side modules are not finalized until after relocation flush_js_optimizer_queue() + if shared.Settings.ASM_JS and closure == 2: + flush_js_optimizer_queue() + + logging.debug('running closure') + # no need to add this to js_transform_tempfiles, because closure and + # debug_level > 0 are never simultaneously true + final = shared.Building.closure_compiler(final, pretty=debug_level >= 1) + if DEBUG: save_intermediate('closure') + log_time('js opts') # Remove some trivial whitespace # TODO: do not run when compress has already been done on all parts of the code diff --git a/emscripten.py b/emscripten.py index 1dc021eb43eb7..bf008b9216f02 100755 --- a/emscripten.py +++ b/emscripten.py @@ -1124,12 +1124,24 @@ def keyfunc(other): asm_setup += '\n' + shared.JS.make_extcall(sig) + '\n' basic_funcs.append('extCall_%s' % sig) + def quote(prop): + if settings['CLOSURE_COMPILER'] == 2: + return "'" + prop + "'" + else: + return prop + + def access_quote(prop): + if settings['CLOSURE_COMPILER'] == 2: + return "['" + prop + "']" + else: + return '.' + prop + # calculate exports exported_implemented_functions = list(exported_implemented_functions) + metadata['initializers'] exported_implemented_functions.append('runPostSets') exports = [] for export in exported_implemented_functions + asm_runtime_funcs + function_tables: - exports.append("%s: %s" % (export, export)) + exports.append(quote(export) + ": " + export) exports = '{ ' + ', '.join(exports) + ' }' # calculate globals try: @@ -1141,9 +1153,9 @@ def keyfunc(other): global_funcs = list(set([key for key, value in forwarded_json['Functions']['libraryFunctions'].iteritems() if value != 2]).difference(set(global_vars)).difference(implemented_functions)) def math_fix(g): return g if not g.startswith('Math_') else g.split('_')[1] - asm_global_funcs = ''.join([' var ' + g.replace('.', '_') + '=global.' + g + ';\n' for g in maths]) + \ - ''.join([' var ' + g + '=env.' + math_fix(g) + ';\n' for g in basic_funcs + global_funcs]) - asm_global_vars = ''.join([' var ' + g + '=env.' + g + '|0;\n' for g in basic_vars + global_vars]) + asm_global_funcs = ''.join([' var ' + g.replace('.', '_') + '=global' + access_quote(g) + ';\n' for g in maths]) + \ + ''.join([' var ' + g + '=env' + access_quote(math_fix(g)) + ';\n' for g in basic_funcs + global_funcs]) + asm_global_vars = ''.join([' var ' + g + '=env' + access_quote(g) + '|0;\n' for g in basic_vars + global_vars]) # In linkable modules, we need to add some explicit globals for global variables that can be linked and used across modules if settings.get('MAIN_MODULE') or settings.get('SIDE_MODULE'): assert settings.get('TARGET_ASMJS_UNKNOWN_EMSCRIPTEN'), 'TODO: support x86 target when linking modules (needs offset of 4 and not 8 here)' @@ -1167,6 +1179,7 @@ def math_fix(g): return real_''' + s + '''.apply(null, arguments); }; ''' for s in exported_implemented_functions if s not in ['_malloc', '_free', '_memcpy', '_memset']]) + receiving += ';\n'.join(['var ' + s + ' = Module["' + s + '"] = asm["' + s + '"]' for s in exported_implemented_functions + function_tables]) # finalize @@ -1184,15 +1197,23 @@ def math_fix(g): // EMSCRIPTEN_START_ASM var asm = (function(global, env, buffer) { %s - var HEAP8 = new global.Int8Array(buffer); - var HEAP16 = new global.Int16Array(buffer); - var HEAP32 = new global.Int32Array(buffer); - var HEAPU8 = new global.Uint8Array(buffer); - var HEAPU16 = new global.Uint16Array(buffer); - var HEAPU32 = new global.Uint32Array(buffer); - var HEAPF32 = new global.Float32Array(buffer); - var HEAPF64 = new global.Float64Array(buffer); - ''' % (asm_setup, "'use asm';" if not metadata.get('hasInlineJS') and not settings['SIDE_MODULE'] and settings['ASM_JS'] == 1 else "'almost asm';") + '\n' + asm_global_vars + ''' + var HEAP8 = new global%s(buffer); + var HEAP16 = new global%s(buffer); + var HEAP32 = new global%s(buffer); + var HEAPU8 = new global%s(buffer); + var HEAPU16 = new global%s(buffer); + var HEAPU32 = new global%s(buffer); + var HEAPF32 = new global%s(buffer); + var HEAPF64 = new global%s(buffer); + ''' % (asm_setup, "'use asm';" if not metadata.get('hasInlineJS') and not settings['SIDE_MODULE'] and settings['ASM_JS'] == 1 else "'almost asm';", + access_quote('Int8Array'), + access_quote('Int16Array'), + access_quote('Int32Array'), + access_quote('Uint8Array'), + access_quote('Uint16Array'), + access_quote('Uint32Array'), + access_quote('Float32Array'), + access_quote('Float64Array')) + '\n' + asm_global_vars + ''' var __THREW__ = 0; var threwValue = 0; var setjmpId = 0; diff --git a/site/build/text/docs/tools_reference/emcc.txt b/site/build/text/docs/tools_reference/emcc.txt index 0d181f6ae3ad6..70626c0c92bfc 100644 --- a/site/build/text/docs/tools_reference/emcc.txt +++ b/site/build/text/docs/tools_reference/emcc.txt @@ -218,11 +218,16 @@ Options that are modified or new in *emcc* are listed below: * "1": Run closure compiler. This greatly reduces code size and may in some cases increase runtime speed (although the opposite can also occur). Note that it takes time to run, and - may require some changes to the code. - - In **asm.js** mode, closure will only be used on the 'shell' code - around the compiled code (the compiled code will be processed by - the custom **asm.js** minifier). + may require some changes to the code. In **asm.js** mode, + closure will only be used on the 'shell' code around the + compiled code (the compiled code will be processed by the + custom **asm.js** minifier). + + * "2": Run closure compiler on *all* the emitted code, even on + **asm.js** output in **asm.js** mode. This can further reduce + code size, but does prevent a significant amount of **asm.js** + optimizations, so it is not recommended unless you want to + reduce code size at all costs. Note: * If closure compiler hits an out-of-memory, try adjusting diff --git a/site/source/docs/tools_reference/emcc.rst b/site/source/docs/tools_reference/emcc.rst index 6a44fcb9fb4e7..1e6d533c0b002 100644 --- a/site/source/docs/tools_reference/emcc.rst +++ b/site/source/docs/tools_reference/emcc.rst @@ -158,9 +158,8 @@ Options that are modified or new in *emcc* are listed below: Runs the :term:`Closure Compiler`. Possible ``on`` values are: - ``0``: No closure compiler (default in ``-O2`` and below). - - ``1``: Run closure compiler. This greatly reduces code size and may in some cases increase runtime speed (although the opposite can also occur). Note that it takes time to run, and may require some changes to the code. - - In **asm.js** mode, closure will only be used on the 'shell' code around the compiled code (the compiled code will be processed by the custom **asm.js** minifier). + - ``1``: Run closure compiler. This greatly reduces code size and may in some cases increase runtime speed (although the opposite can also occur). Note that it takes time to run, and may require some changes to the code. In **asm.js** mode, closure will only be used on the 'shell' code around the compiled code (the compiled code will be processed by the custom **asm.js** minifier). + - ``2``: Run closure compiler on *all* the emitted code, even on **asm.js** output in **asm.js** mode. This can further reduce code size, but does prevent a significant amount of **asm.js** optimizations, so it is not recommended unless you want to reduce code size at all costs. .. note:: diff --git a/tests/test_other.py b/tests/test_other.py index 45fd7f2c0e32a..5c2c626d47d19 100644 --- a/tests/test_other.py +++ b/tests/test_other.py @@ -3978,12 +3978,13 @@ def get_size(name): test(['-O1']) def test_no_nuthin(self): - def test(opts, ratio): + def test(opts, ratio, absolute): print opts def get_size(name): return os.stat(name).st_size sizes = {} def do(name, moar_opts): + self.clear() Popen([PYTHON, EMCC, path_from_root('tests', 'hello_world.c'), '-o', name + '.js'] + opts + moar_opts).communicate() sizes[name] = get_size(name + '.js') self.assertContained('hello, world!', run_js(name + '.js')) @@ -3997,10 +3998,12 @@ def do(name, moar_opts): assert sizes['no_nuthin'] < sizes['no_fs'] assert sizes['no_nuthin'] < sizes['no_browser'] assert sizes['no_nuthin'] < ratio*sizes['normal'] - test([], 0.66) - test(['-O1'], 0.66) - test(['-O2'], 0.50) - test(['-O3', '--closure', '1'], 0.60) + assert sizes['no_nuthin'] < absolute + test([], 0.66, 250000) + test(['-O1'], 0.66, 225000) + test(['-O2'], 0.50, 75000) + test(['-O3', '--closure', '1'], 0.60, 60000) + test(['-O3', '--closure', '2'], 0.60, 40000) # might change now and then def test_stat_fail_alongtheway(self): open('src.cpp', 'w').write(r''' From 6fb578efe9cbf7bb81b1ff7f8cd8a7d6ace4d4d9 Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Fri, 22 Aug 2014 13:09:34 -0700 Subject: [PATCH 25/60] remove old asmPrintInt and Float funcs --- emscripten.py | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/emscripten.py b/emscripten.py index bf008b9216f02..3face4016baf4 100755 --- a/emscripten.py +++ b/emscripten.py @@ -1023,7 +1023,7 @@ def fix_item(item): if settings['PRECISE_F32']: maths += ['Math.fround'] - basic_funcs = ['abort', 'assert', 'asmPrintInt', 'asmPrintFloat'] + [m.replace('.', '_') for m in math_envs] + basic_funcs = ['abort', 'assert'] + [m.replace('.', '_') for m in math_envs] if settings['RESERVED_FUNCTION_POINTERS'] > 0: basic_funcs.append('jsCall') if settings['SAFE_HEAP']: basic_funcs += ['SAFE_HEAP_LOAD', 'SAFE_HEAP_STORE', 'SAFE_FT_MASK'] if settings['CHECK_HEAP_ALIGN']: basic_funcs += ['CHECK_ALIGN_2', 'CHECK_ALIGN_4', 'CHECK_ALIGN_8'] @@ -1188,12 +1188,6 @@ def math_fix(g): funcs_js = [''' %s - function asmPrintInt(x, y) { - Module.print('int ' + x + ',' + y);// + ' ' + new Error().stack); - } - function asmPrintFloat(x, y) { - Module.print('float ' + x + ',' + y);// + ' ' + new Error().stack); - } // EMSCRIPTEN_START_ASM var asm = (function(global, env, buffer) { %s From a4d6e2b92a9b11b34b3cf9e9f552bc3dd1ceab89 Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Fri, 22 Aug 2014 14:16:01 -0700 Subject: [PATCH 26/60] do not include stdlibs that were not forced, if we asked for only forced ones --- tools/system_libs.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/system_libs.py b/tools/system_libs.py index 13eb8b9cd097e..c86650bce015d 100644 --- a/tools/system_libs.py +++ b/tools/system_libs.py @@ -538,7 +538,7 @@ class Dummy: if haz in need: need.remove(haz) if shared.Settings.VERBOSE: logging.debug('considering %s: we need %s and have %s' % (name, str(need), str(has))) - if force_this or len(need) > 0: + if force_this or (len(need) > 0 and not only_forced): if apply_(need): # We need to build and link the library in logging.debug('including %s' % name) From d398386b7620ac9abc16741170485af2a8518046 Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Fri, 22 Aug 2014 14:44:22 -0700 Subject: [PATCH 27/60] update community page --- site/source/docs/introducing_emscripten/community.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/site/source/docs/introducing_emscripten/community.rst b/site/source/docs/introducing_emscripten/community.rst index abaf79a05bec9..5306e61319484 100644 --- a/site/source/docs/introducing_emscripten/community.rst +++ b/site/source/docs/introducing_emscripten/community.rst @@ -17,12 +17,11 @@ The best ways to contact us for support are the *mailing list* and the *IRC* cha - Mailing list: `emscripten-discuss `_ - IRC: **#emscripten** on `irc.mozilla.org `_ +Emscripten also has a presence on social media: -Emscripten also has an *unofficial* presence on social media: - -- `Google+ page `_ - `#emscripten `_ (Emscripten Hashtag on Twitter) -- `@kripken `_ (Emscripten Developer Account on Twitter) +- Unofficial `Google+ page `_ +- `@kripken `_ (an Emscripten developer's account on Twitter, mentions Emscripten updates) Report a bug From 0cfded86983d8d7374a872797bcff00a9e05d3fb Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Fri, 22 Aug 2014 14:47:05 -0700 Subject: [PATCH 28/60] bug reports page updates --- site/source/docs/getting_started/bug_reports.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/site/source/docs/getting_started/bug_reports.rst b/site/source/docs/getting_started/bug_reports.rst index de177d5026131..b47d5a08db461 100644 --- a/site/source/docs/getting_started/bug_reports.rst +++ b/site/source/docs/getting_started/bug_reports.rst @@ -9,12 +9,12 @@ All bugs should be filed in the GitHub `main Date: Fri, 22 Aug 2014 14:57:56 -0700 Subject: [PATCH 29/60] tutorial updates --- site/source/docs/getting_started/Tutorial.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/site/source/docs/getting_started/Tutorial.rst b/site/source/docs/getting_started/Tutorial.rst index a65eb01800512..7098331b8a77d 100644 --- a/site/source/docs/getting_started/Tutorial.rst +++ b/site/source/docs/getting_started/Tutorial.rst @@ -13,7 +13,7 @@ First things first Make sure you have :ref:`downloaded and installed ` Emscripten (the exact approach for doing this will depend your operating system: Linux, Windows, or Mac). -Emscripten is accessed using the :ref:`emccdoc`. This script invokes all the other tools needed to build your code, and can act as a drop-in replacement for a standard compiler like *gcc*. It is called on the command line using ``./emcc`` or ``./em++``. +Emscripten is accessed using the :ref:`emccdoc`. This script invokes all the other tools needed to build your code, and can act as a drop-in replacement for a standard compiler like *gcc* or *clang*. It is called on the command line using ``./emcc`` or ``./em++``. .. note:: On Windows the tool is called using the slightly different syntax: ``emcc`` or ``em++``. The remainder of this tutorial uses the Linux approach (``./emcc``). @@ -42,15 +42,15 @@ Running Emscripten You can now compile your first C++ file to JavaScript. -First, lets have a look at the file to be compiled: **hello_world.cpp**. This is the simplest test code in the SDK, and as you can see, all it does is print "hello, world!" to the console and then exit. +First, lets have a look at the file to be compiled: **hello_world.c**. This is the simplest test code in the SDK, and as you can see, all it does is print "hello, world!" to the console and then exit. -.. include:: ../../../../tests/hello_world.cpp +.. include:: ../../../../tests/hello_world.c :literal: To build the JavaScript version of this code, simply specify the C++ file after *emcc*: :: - ./emcc tests/hello_world.cpp + ./emcc tests/hello_world.c There should now be an **a.out.js** file in the current directory. Run it using :term:`node.js`: @@ -70,7 +70,7 @@ Generating HTML Emscripten can also generate HTML for testing embedded JavaScript. To generate HTML, use the ``-o`` (:ref:`output `) command and specify an html file as the target file: :: - ./emcc tests/hello_world.cpp -o hello.html + ./emcc tests/hello_world.c -o hello.html Open the web page in a web browser. As you can see, the framework defines a text area for displaying the output of the ``printf()`` calls in the native code. @@ -116,7 +116,7 @@ The following command is used to preload the data file. The ``--preload-file`` o Open ``hello.html`` in the *Firefox web browser* to see the data from **hello_world_file.txt** being displayed. -.. note:: Unfortunately *Chrome* and *Internet Explorer* do not support ``file://`` :term:`XHR` requests, and can't directly load the local file in which preloaded data is stored. For these browsers you'll need to serve the files using a webserver. The easiest way to do this is to use the python **SimpleHTTPServer** (in the current directory do ``python -m SimpleHTTPServer 8080`` and then open ``localhost:8080/hello.html``). +.. note:: Unfortunately *Chrome* and *Internet Explorer* do not support ``file://`` :term:`XHR` requests, and can't directly load the local file in which preloaded data is stored. For these browsers you'll need to serve the files using a webserver. The easiest way to do this is to use the python **SimpleHTTPServer** (in the current directory do ``python -m SimpleHTTPServer 8080`` and then open ``http://localhost:8080/hello.html``). For more information about working with the file system see the :ref:`Filesystem-Guide`, :ref:`Filesystem-API` and :ref:`Synchronous-virtual-XHR-backed-file-system-usage`. @@ -124,7 +124,7 @@ For more information about working with the file system see the :ref:`Filesystem Optimizing code =============== -Emscripten, like *gcc*, generates unoptimized code by default. You can generate :ref:`slightly-optimized ` code with the ``-O1`` command line argument (run the test code from the :term:`SDK root directory`): :: +Emscripten, like *gcc* and *clang*, generates unoptimized code by default. You can generate :ref:`slightly-optimized ` code with the ``-O1`` command line argument (run the test code from the :term:`SDK root directory`): :: ./emcc -O1 tests/hello_world.cpp From 4bc2c012b959563e547d09cc5343e6fec75285c1 Mon Sep 17 00:00:00 2001 From: hamishwillee Date: Sat, 23 Aug 2014 08:45:22 +1000 Subject: [PATCH 30/60] general fixes to FAQ and some of the getting started articles --- ...lly_integrating_emscripten_with_vs2010.rst | 7 +- .../verify_emscripten_environment.rst | 6 +- site/source/docs/getting_started/FAQ.rst | 220 ++++++++++-------- ...ing_started_with_emscripten_and_vs2010.rst | 67 ++++-- 4 files changed, 186 insertions(+), 114 deletions(-) diff --git a/site/source/docs/building_from_source/manually_integrating_emscripten_with_vs2010.rst b/site/source/docs/building_from_source/manually_integrating_emscripten_with_vs2010.rst index 2490bd3568c40..9c7012bbefc6e 100644 --- a/site/source/docs/building_from_source/manually_integrating_emscripten_with_vs2010.rst +++ b/site/source/docs/building_from_source/manually_integrating_emscripten_with_vs2010.rst @@ -32,8 +32,11 @@ Install the vs-tool plugin #. Set up the required environment variables for *vs-tool*. - #. Windows 7: Open **Control Panel | System | Advanced System Settings | Environment Variables**. - #. Windows 8: Right click on the **Windows menu icon | System | Advanced System Settings | Environment Variables**. + #. Open the Environment Variables setting: + + - Windows 7: Open **Control Panel | System | Advanced System Settings | Environment Variables**. + - Windows 8: Right click on the **Windows menu icon | System | Advanced System Settings | Environment Variables**. + #. Create a new environment variable ``CLANG_BIN`` and set it to point to the folder where you built *Fastcomp* (path to **clang.exe**) E.g.: :: diff --git a/site/source/docs/building_from_source/verify_emscripten_environment.rst b/site/source/docs/building_from_source/verify_emscripten_environment.rst index 53b5091a567ab..51e3852da02fe 100644 --- a/site/source/docs/building_from_source/verify_emscripten_environment.rst +++ b/site/source/docs/building_from_source/verify_emscripten_environment.rst @@ -43,9 +43,11 @@ At this point you need to :ref:`Install and activate ` are known to build and pass on the **master** branch, so it is likely that there is some problem with your environment. -- **Q.** I get lots of errors building the tests or even simple hello world type stuff? +First call ``./emcc -v``, which runs basic sanity checks and prints out useful environment information. If that doesn't help, follow the instructions in :ref:`verifying-the-emscripten-environment`. - **A.** Try to run ``emcc -v``, which prints out some helpful information and runs some sanity checks. You can also try ``emcc --clear-cache`` to empty the compiler's internal cache, which will then be rebuilt next time it is used. If none of those help or give an idea of what could be the matter, then some common problems to check for are: +You might also want to go through the :ref:`Tutorial` again, as this is updated as Emscripten changes. - - Typos in the paths in ``~/.emscripten``. - - Using older versions of Node or JS engines. Use the versions mentioned in the :ref:`Tutorial`. - - Using older versions of LLVM. See the :ref:`Emscripten-SDK` page for which version of LLVM is supported. Using other builds might not work. If you are using fastcomp, see :ref:`LLVM-Backend` for the proper repos for LLVM and clang that you should be using. - - Not having ``python2`` in your system. For compatibility with systems that install python 2.x alongside 3.x (increasingly common), we look for ``python2``. If you only have python 2.x installed, make ``python2`` be a link to ``python``. Or, instead you can invoke our python scripts directly, for example - ``python emcc`` instead of ``./emcc``. - You might also want to go through the :ref:`Tutorial` again, if it's been a while since you have (we update it when things change). +I tried something and it doesn't work? +====================================== -- **Q.** I tried something and it doesn't work? +This site has comprehensive documentation. If you tried "something" and it fails (for example a :ref:`compiler flag `, or a *libc* function), one of the first options should therefore be to search the site. - **A.** Emscripten has an extensive test suite. If you try something (a compiler flag, a libc function, etc.) and it fails, often the best thing is to ``grep -r`` in ``tests/`` to see if there is a test for it. On the master branch, **all** tests are known to pass. The tests can therefore both show you what works, and also they give concrete examples for how to use things, which can be helpful in addition to the docs. +Another really good option is to see if there is a test for the failing functionality in the :ref:`Emscripten test suite ` (run ``grep -r`` in ``tests/``). **All** the tests are known to pass on the master branch, so they provide concrete "known-good" examples of how various options and code are used. -- **Q.** Can I compile my project using Emscripten? Do I need a new build system? - **A.** You can in most cases very easily use your project's current build system with Emscripten. See :ref:`Building-Projects`. +Do I need to change my build system to use Emscripten? +====================================================== -- **Q.** My code cannot access a file that is right there in the same directory? +In most cases you will be able to use your project's current build system with Emscripten. See :ref:`Building-Projects`. - **A.** Emscripten-generated code cannot by default access local files on your machine like a native application. See :ref:`Filesystem-Guide` - for details: you can in node allow such access, and in other platforms you can use preloading to work around lack of synchronous file IO. -- **Q.** My code compiles slowly. +My code cannot access a file in the same directory? +=================================================== - **A.** Emscripten makes some tradeoffs that make the generated code faster and smaller, at the cost of longer compilation times. For example, we build parts of the standard library along with your code which enables some additional optimizations, but takes a little longer to compile. +Emscripten-generated code cannot by default access local files on your machine like a native application. See :ref:`Filesystem-Guide` for details: you can in node allow such access, and in other platforms you can use preloading to work around lack of synchronous file IO. - Emscripten can run some passes in parallel (specifically, the JS opts), and will do so automatically, so running on a machine with more cores can give you almost a linear speedup (so doubling the amount of cores can almost halve the amount of time it takes to build and so forth). To see details of how work is parallelized, compile with ``EMCC_DEBUG=1`` in the environment (note though that in that debug mode compilation takes longer than normal, because we print out a lot of intermediate steps to disk, by default to ``/tmp/emscripten_temp``, but it's still useful to see which stages are slowing you down). You can affect how many cores are using with ``EMCC_CORES=N``, which can be useful if you have many cores but relatively less memory. - Note that optimization can in some cases be noticeably slower than unoptimized code, ``-O1`` is slower than ``-O0``, which in turn is slower than ``-O2`` (in return, though, they greatly improve the speed of the generated code). It might be useful to use ``-O0`` (or not specify an optimization level) during quick development iterations and to do fully optimized builds less frequently. Note that ``-O3`` is **especially** slow (you can mitigate the ``-O3`` slowness by also enabling ``-s AGGRESSIVE_VARIABLE_ELIMINATION=1``, as it removes variables which makes the ``-O3`` regalloc easier). +My code compiles slowly. +======================== - Currently builds with line-number debug info (where the source code was compiled with ``-g``) are slow, see issue #216. Stripping the debug info leads to much faster compile times. +Emscripten makes some tradeoffs that make the generated code faster and smaller, at the cost of longer compilation times. For example, we build parts of the standard library along with your code which enables some additional optimizations, but takes a little longer to compile. -- **Q.** My code runs slowly. +Emscripten can run some passes in parallel (specifically, the JS opts), and will do so automatically, so running on a machine with more cores can give you almost a linear speedup (so doubling the amount of cores can almost halve the amount of time it takes to build and so forth). To see details of how work is parallelized, compile with ``EMCC_DEBUG=1`` in the environment (note though that in that debug mode compilation takes longer than normal, because we print out a lot of intermediate steps to disk, by default to ``/tmp/emscripten_temp``, but it's still useful to see which stages are slowing you down). You can affect how many cores are using with ``EMCC_CORES=N``, which can be useful if you have many cores but relatively less memory. - **A.** Make sure you build with ``-O2`` so code is optimized. **This is necessary both for each source file, and for the final stage of linking and compiling to JS**, see more details :ref:`Building-Projects`. See :ref:`Optimizing-Code` for more info. +Note that optimization can in some cases be noticeably slower than unoptimized code, ``-O1`` is slower than ``-O0``, which in turn is slower than ``-O2`` (in return, though, they greatly improve the speed of the generated code). It might be useful to use ``-O0`` (or not specify an optimization level) during quick development iterations and to do fully optimized builds less frequently. Note that ``-O3`` is **especially** slow (you can mitigate the ``-O3`` slowness by also enabling ``-s AGGRESSIVE_VARIABLE_ELIMINATION=1``, as it removes variables which makes the ``-O3`` regalloc easier). -- **Q.** My code is large. +Currently builds with line-number debug info (where the source code was compiled with ``-g``) are slow, see issue #216. Stripping the debug info leads to much faster compile times. - **A.** Make sure you build with ``-O2`` so code is optimized, which includes minification to reduce size. You should also set up gzip compression on your webserver, which all browsers now support. - You can use closure compile to reduce code size even more with ``--closure 1``, however that will require that your code with with closure compiler advanced optimizations, including proper exports and so forth. It is usually not worth the effort over an optimized build+server gzip. +My code runs slowly. +===================== -- **Q.** When I compile code that should work, I get odd errors in Emscripten about various things. I get different errors (or it works) on another machine. +Make sure you build with ``-O2`` so code is optimized. **This is necessary both for each source file, and for the final stage of linking and compiling to JS**, see more details :ref:`Building-Projects`. See :ref:`Optimizing-Code` for more info. - **A.** Make sure you are using the Emscripten bundled system headers. Using ``emcc`` will do so by default, but if you compile into LLVM bitcode yourself, or you use your local system headers even with ``emcc``, problems can happen. -- **Q.** My large codebase runs ok, but the time it takes to start up is significant. What can I do to improve that? +My code is large. +=========================== - **A.** First, make sure you are running an optimized build (which will be much smaller and faster to start up). Then, if the sheer code size is causing the slow startup, you can try the `outlining option in emscripten `__. +Make sure you build with ``-O2`` so code is optimized, which includes minification to reduce size. You should also set up gzip compression on your webserver, which all browsers now support. - Another possible factor is network latency. If you load data off the network and also have a big codebase, try to put the file loading code in a separate script element - that is, run the file packager (``tools/file_packager.py``) and put its code in one script element, and in another script element after it put the generated codebase. That will allow the browser to start the network download immediately, so it can run in parallel to the browser parsing and starting up the codebase. +You can use closure compile to reduce code size even more with ``--closure 1``, however that will require that your code with with closure compiler advanced optimizations, including proper exports and so forth. It is usually not worth the effort over an optimized build+server gzip. -- **Q.** My code fails to compile, the error includes something about inline assembly (or ``{"text":"asm"}``). - **A.** Emscripten cannot compile inline assembly code, which is CPU specific, because Emscripten is not a CPU emulator. +When I compile code that should work, I get odd errors in Emscripten about various things. I get different errors (or it works) on another machine. +========================================================================================================================================================================== - Many projects have build options that generate only platform-independent code, without inline assembly. That should be used for Emscripten. For example, the following might help (and are done automatically for you by ``emcc``): +Make sure you are using the Emscripten bundled system headers. Using ``emcc`` will do so by default, but if you compile into LLVM bitcode yourself, or you use your local system headers even with ``emcc``, problems can happen. + + +My large codebase runs ok, but the time it takes to start up is significant. What can I do to improve that? +======================================================================================================================================== + +First, make sure you are running an optimized build (which will be much smaller and faster to start up). Then, if the sheer code size is causing the slow startup, you can try the `outlining option in emscripten `__. + +Another possible factor is network latency. If you load data off the network and also have a big codebase, try to put the file loading code in a separate script element - that is, run the file packager (``tools/file_packager.py``) and put its code in one script element, and in another script element after it put the generated codebase. That will allow the browser to start the network download immediately, so it can run in parallel to the browser parsing and starting up the codebase. + + +My code fails to compile, the error includes something about inline assembly (or ``{"text":"asm"}``). +======================================================================================================================================== + +Emscripten cannot compile inline assembly code, which is CPU specific, because Emscripten is not a CPU emulator. + +Many projects have build options that generate only platform-independent code, without inline assembly. That should be used for Emscripten. For example, the following might help (and are done automatically for you by ``emcc``): :: #undef __i386__ #undef __x86_64__ - Since when no CPU-specific ``#define`` exists, many projects will not generate CPU specific code. In general though, you will need to find where inline assembly is generated, and how to disable that. +Since when no CPU-specific ``#define`` exists, many projects will not generate CPU specific code. In general though, you will need to find where inline assembly is generated, and how to disable that. + + +How do I run an event loop? +=========================== -- **Q.** How do I run an event loop? +To run a C function repeatedly, use :c:func:`emscripten_set_main_loop` (**emscripten.h**). The other functions in that file are also useful, they let you do things like add events that block the main loop, etc. - **A.** To run a C function repeatedly, use :c:func:`emscripten_set_main_loop` (**emscripten.h**). The other functions in that file are also useful, they let you do things like add events that block the main loop, etc. +To respond to browser events and so forth, use the SDL API normally. See the SDL tests for examples (look for SDL in ``tests/runner.py``). - To respond to browser events and so forth, use the SDL API normally. See the SDL tests for examples (look for SDL in ``tests/runner.py``). +See also the next question. - See also the next question. -- **Q.** My HTML app hangs. +My HTML app hangs. +================== **A.** Graphical C++ apps typically have a main loop that is an infinite loop, in which event handling is done, processing and rendering, then SDL_Delay. However, in JS there is no way for SDL_Delay to actually return control to the browser event loop. To do that, you must exit the current code. See :ref:`Emscripten-Browser-Environment`. -- **Q.** My SDL app doesn't work. +My SDL app doesn't work. +======================== - **A.** See the SDL automatic tests for working examples: ``python tests/runner.py browser``. +See the SDL automatic tests for working examples: ``python tests/runner.py browser``. -- **Q.** How do I link against system libraries like SDL, boost, etc.? +How do I link against system libraries like SDL, boost, etc.? +================================================================== - **A.** System libraries that are included with emscripten - libc, libc++ (C++ standard library) and SDL - are automatically included when you compile (and just the necessary parts of them). You don't even need ``-lSDL``, unlike other compilers (but ``-lSDL`` won't hurt either). +System libraries that are included with Emscripten - libc, libc++ (C++ standard library) and SDL - are automatically included when you compile (and just the necessary parts of them). You don't even need ``-lSDL``, unlike other compilers (but ``-lSDL`` won't hurt either). - Other libraries not included with emscripten, like boost, you would need to compile yourself and link with your program, just as if they were a module in your project. For example, see how `BananaBread links in libz `_. - (Note that in the specific case of boost, if you only need the boost headers, you don't need to compile anything.) +Other libraries not included with Emscripten, like boost, you would need to compile yourself and link with your program, just as if they were a module in your project. For example, see how `BananaBread links in libz `_. (Note that in the specific case of boost, if you only need the boost headers, you don't need to compile anything.) - Another option for libraries not included is to implement them as a JS library, like emscripten does for libc (minus malloc) and SDL (but not libc++ or malloc). See ``--js-library`` in emcc. +Another option for libraries not included is to implement them as a JS library, like emscripten does for libc (minus malloc) and SDL (but not libc++ or malloc). See ``--js-library`` in emcc. -- **Q.** How can my compiled program access files? - **A.** Emscripten uses a virtual file system that may be preloaded with data or linked to URLs for lazy loading. See the :ref:`Filesystem-Guide` for more details. +How can my compiled program access files? +================================================================== -- **Q.** Functions in my C/C++ source code vanish when I compile to JavaScript, and/or I get ``No functions to process``..? +Emscripten uses a virtual file system that may be preloaded with data or linked to URLs for lazy loading. See the :ref:`Filesystem-Guide` for more details. + + +Functions in my C/C++ source code vanish when I compile to JavaScript, and/or I get ``No functions to process``..? +================================================================================================================== **A.** By default Emscripten does dead code elimination to minimize code size. However, it might end up removing functions you want to call yourself, that are not called from the compiled code (so the LLVM optimizer thinks they are unneeded). You can run emcc with ``-s LINKABLE=1`` which will disable link-time optimizations and dead code elimination, but this makes the code larger and less optimized than it could be. Instead, you should prevent specific functions from being eliminated by adding them to EXPORTED_FUNCTIONS (see ``src/settings.js``), for example, run emcc with something like ``-s EXPORTED_FUNCTIONS="['_main', '_my_func']"`` in order to keep my_func from being removed/renamed (as well as ``main()``)). Note that this assumes my_func is a C function, otherwise you would need to write out the C++ name mangling. @@ -124,69 +148,83 @@ FAQ (wiki-import) Note: In LLVM 3.2 dead code elimination is significantly more aggressive. All functions not kept alive through EXPORTED_FUNCTIONS will be potentially eliminated. Make sure to keep the things you need alive using one or both of those methods. -- **Q.** The FS API is not available when I build with closure? - - **A.** Closure compiler will minify the FS API code. To write code that uses it, it must be optimized **with** the FS API code by closure. To do that, use emcc's ``--pre-js`` option, see ``emcc --help``. +The FS API is not available when I build with closure? +======================================================= -- **Q.** My code breaks with ``-O2 --closure 1``, giving odd errors..? +Closure compiler will minify the FS API code. To write code that uses it, it must be optimized **with** the FS API code by closure. To do that, use emcc's ``--pre-js`` option, see ``emcc --help``. - **A.** The likely problem is that Closure Compiler minifies variable names. Names like ``i,j,xa`` can be generated, and if other code has such variables in the global scope, bad things can happen. - To check if this is the problem, compile with ``-O2`` (without ``--closure 1``). If that works, name minification might be the problem. If so, wrapping the generated code in a closure should fix it. (Or, wrap your other code in a closure, or stop it from using small variable names in the global scope, you might be using such variables by mistake by forgetting a ``var`` and assigning to a variable - which makes it be in the global scope.) +My code breaks with ``-O2 --closure 1``, giving odd errors..? +==================================================================== - To 'wrap' code in a closure, do something like this: +The likely problem is that Closure Compiler minifies variable names. Names like ``i,j,xa`` can be generated, and if other code has such variables in the global scope, bad things can happen. + +To check if this is the problem, compile with ``-O2`` (without ``--closure 1``). If that works, name minification might be the problem. If so, wrapping the generated code in a closure should fix it. (Or, wrap your other code in a closure, or stop it from using small variable names in the global scope, you might be using such variables by mistake by forgetting a ``var`` and assigning to a variable - which makes it be in the global scope.) + +To 'wrap' code in a closure, do something like this: :: - var CompiledModule = (function() { - .. GENERATED CODE .. - return Module; - })(); + var CompiledModule = (function() { + .. GENERATED CODE .. + return Module; + })(); -- **Q.** I get ``undefined is not a function`` or ``NAME is not a function``..? +I get ``undefined is not a function`` or ``NAME is not a function``..? +===================================================================================== - **A.** The likely cause is an undefined function - something that was referred to, but not implemented or linked in. If you get ``undefined``, look at the line number to see the function name. +The likely cause is an undefined function - something that was referred to, but not implemented or linked in. If you get ``undefined``, look at the line number to see the function name. - Emscripten by default does *not* give fatal errors on undefined symbols, so you can get runtime errors like these (because in practice in many codebases it is easiest to get them working without refactoring them to remove all undefined symbol calls). If you prefer compile-time notifications, run emcc with - ``-s WARN_ON_UNDEFINED_SYMBOLS=1`` or ``-s ERROR_ON_UNDEFINED_SYMBOLS=1``. +Emscripten by default does *not* give fatal errors on undefined symbols, so you can get runtime errors like these (because in practice in many codebases it is easiest to get them working without refactoring them to remove all undefined symbol calls). If you prefer compile-time notifications, run emcc with ``-s WARN_ON_UNDEFINED_SYMBOLS=1`` or ``-s ERROR_ON_UNDEFINED_SYMBOLS=1``. - Aside from just forgetting to link in a necessary object file, one possible cause for this error is inline functions in headers. If you have a header with ``inline int my_func() { .. }`` then clang may not actually inline the function (since inline is just a hint), and also not generate code for it (since it's in a header), so the generated bitcode and js will not have that function implemented. One solution is to add ``static``, that is ``static inline int my_func() { .. }`` which forces code to be generated in the object file. +Aside from just forgetting to link in a necessary object file, one possible cause for this error is inline functions in headers. If you have a header with ``inline int my_func() { .. }`` then clang may not actually inline the function (since inline is just a hint), and also not generate code for it (since it's in a header), so the generated bitcode and js will not have that function implemented. One solution is to add ``static``, that is ``static inline int my_func() { .. }`` which forces code to be generated in the object file. -- **Q.** I get an odd python error complaining about libcxx.bc or libcxxabi.bc..? +I get an odd python error complaining about libcxx.bc or libcxxabi.bc..? +===================================================================================== - **A.** Possibly building libcxx or libcxxabi failed. Go to system/lib/libcxx (or libcxxabi) and do ``emmake make`` to see the actual error. Or, clean the emscripten cache (``~/.emscripten_cache``) and then compile your file with ``EMCC_DEBUG=1`` in the environment. libcxx will then be built in + +Possibly building libcxx or libcxxabi failed. Go to system/lib/libcxx (or libcxxabi) and do ``emmake make`` to see the actual error. Or, clean the emscripten cache (``~/.emscripten_cache``) and then compile your file with ``EMCC_DEBUG=1`` in the environment. libcxx will then be built in ``/tmp/emscripten_temp/libcxx``, and you can see ``configure*,make*`` files that are the output of configure and make, etc. - One possible cause of this error is the lack of ``make``, which is necessary to build these libraries. If you are on Windows, you need cygwin which supplies ``make``. +One possible cause of this error is the lack of ``make``, which is necessary to build these libraries. If you are on Windows, you need cygwin which supplies ``make``. + +Running LLVM bitcode generated by emcc through ``lli`` breaks with errors about ``impure_ptr`` stuff..? +======================================================================================================== -- **Q.** Running LLVM bitcode generated by emcc through ``lli`` breaks with errors about ``impure_ptr`` stuff..? +First of all, lli is not maintained (sadly) and has odd errors and crashes. However there is ``tools/nativize_llvm.py`` which compiles bitcode to a native executable. It will also hit the ``impure_ptr`` error though. - **A.** First of all, lli is not maintained (sadly) and has odd errors and crashes. However there is ``tools/nativize_llvm.py`` which compiles bitcode to a native executable. It will also hit the ``impure_ptr`` error though. +The issue is that newlib uses that impure pointer stuff, while glibc uses something else. So bitcode build with the emscripten SDK (which emcc does) will not run locally, unless your machine uses newlib (which basically only embedded systems do). The impure_ptr stuff is limited, however, it only applies to explicit use of ``stdout`` etc. So ``printf(..)`` will work, but ``fprintf(stdout, ..)`` will not. So often it is simple to modify your code to not hit this problem. - The issue is that newlib uses that impure pointer stuff, while glibc uses something else. So bitcode build with the emscripten SDK (which emcc does) will not run locally, unless your machine uses newlib (which basically only embedded systems do). The impure_ptr stuff is limited, however, it only applies to explicit use of ``stdout`` etc. So ``printf(..)`` will work, but ``fprintf(stdout, ..)`` will not. So often it is simple to modify your code to not hit this problem. +I get a stack size error when optimizing (``RangeError: Maximum call stack size exceeded`` or similar)? +======================================================================================================================================= -- **Q.** I get a stack size error when optimizing (``RangeError: Maximum call stack size exceeded`` or similar)? +You may need to increase the stack size for node. On linux and mac, you can just do ``NODE_JS = ['node', '--stack_size=8192']`` or such (in ``~/.emscripten``). On windows, you will also need ``--max-stack-size=8192``, and also to run ``editbin /stack:33554432 node.exe``. - **A.** You may need to increase the stack size for node. On linux and mac, you can just do ``NODE_JS = ['node', '--stack_size=8192']`` or such (in ``~/.emscripten``). On windows, you will also need ``--max-stack-size=8192``, and also to run ``editbin /stack:33554432 node.exe``. -- **Q.** I get ``error: cannot compile this aggregate va_arg expression yet`` and it says ``compiler frontend failed to generate LLVM bitcode, halting`` afterwards. +I get ``error: cannot compile this aggregate va_arg expression yet`` and it says ``compiler frontend failed to generate LLVM bitcode, halting`` afterwards. +============================================================================================================================================================================================= - **A.** This is a limitation of the le32 frontend in clang. You can use the x86 frontend instead by compiling with ``EMCC_LLVM_TARGET=i386-pc-linux-gnu`` in the environment (however you will lose the advantages of le32 which includes better alignment of doubles). +This is a limitation of the le32 frontend in clang. You can use the x86 frontend instead by compiling with ``EMCC_LLVM_TARGET=i386-pc-linux-gnu`` in the environment (however you will lose the advantages of le32 which includes better alignment of doubles). .. _faq-when-safe-to-call-compiled-functions: -- **Q.** I am building a library, and sometimes I get an error when I call a compiled function before the page fully loaded. How can I tell when is safe to call it? +I am building a library, and sometimes I get an error when I call a compiled function before the page fully loaded. How can I tell when is safe to call it? +============================================================================================================================================================================ - **A.** The easiest way to find out when loading is complete (which is asynchronous, as it often requires loading files, such as the .mem file or preloade files), is to just add a ``main()`` function. It will be called when it is safe to do so, after startup is complete, so that is a signal that it is safe to call any compiled method. - You can make ``main()`` call your JS to notify it, for example if ``allReady()`` is a JS function you want called when everything is ready, you can do +The easiest way to find out when loading is complete (which is asynchronous, as it often requires loading files, such as the .mem file or preloade files), is to just add a ``main()`` function. It will be called when it is safe to do so, after startup is complete, so that is a signal that it is safe to call any compiled method. - :: +You can make ``main()`` call your JS to notify it, for example if ``allReady()`` is a JS function you want called when everything is ready, you can do + +:: + + #include - #include - int main() { - EM_ASM( allReady() ); - } + int main() { + EM_ASM( allReady() ); + } -- **Q.** The name of the project sounds weird to me. + +The name of the project sounds weird to me +========================================== - **A.** I don't know why; it's a perfectly `cromulent `_ word! +I don't know why; it's a perfectly `cromulent `_ word! diff --git a/site/source/docs/getting_started/getting_started_with_emscripten_and_vs2010.rst b/site/source/docs/getting_started/getting_started_with_emscripten_and_vs2010.rst index c958c2cba5ca0..7be256352e598 100644 --- a/site/source/docs/getting_started/getting_started_with_emscripten_and_vs2010.rst +++ b/site/source/docs/getting_started/getting_started_with_emscripten_and_vs2010.rst @@ -1,40 +1,69 @@ -.. _getting-started-emscripten-from-vs2010: +.. _getting-started-emscripten-from-visual-studio: -=========================================================================================== -Getting started using Emscripten from the Visual Studio 2010 IDE (under-construction) -=========================================================================================== +====================================================================== +Getting started using Emscripten from Visual Studio (ready-for-review) +====================================================================== -Windows Developers who want to use an IDE can develop and compile their Emscripten projects from `Microsoft Visual Studio 2010 `_. This article shows you how. +Windows Developers can develop, compile, and launch, their Emscripten projects from `Microsoft Visual Studio 2010 `_ (only). This topic shows you how. -.. note:: Visual Studio 2011 and 2012 are not supported. +.. warning:: Visual Studio 2011 and 2012 are not supported. Integrating Emscripten and Visual Studio ======================================== -The integration is enabled the :term:`vs-tool` plugin. +Emscripten is integrated into Visual Studio (2010) using the :term:`vs-tool` plugin, which is is automatically deployed by the :term:`Windows NSIS Installer Emscripten SDK` if *Visual Studio 2010* is present on your system at install time (it is also possible to :ref:`manually integrate Emscripten into Visual Studio 2010 `). -This plugin is automatically deployed by the :term:`Windows NSIS Installer Emscripten SDK` if *Visual Studio 2010* is present on your system. It is also possible to :ref:`manually integrate Emscripten into Visual Studio 2010 `. +The *vs-tool* plugin adds an **Emscripten** configuration to the list of available *Solution Configurations* in Visual Studio. Activate this configuration for a solution/project to make Visual Studio run the project build through Emscripten, producing **.html** or **.js** output depending on the configured project properties. -The *vs-tool* plugin adds an 'Emscripten' configuration to the list of available *Solution Configurations* in Visual Studio. Activate this configuration for a solution/project to make Visual Studio run the project build through Emscripten, producing **.html** or **.js** output depending on the configured project properties. How to build a Visual Studio solution using Emscripten -================================================================================ +====================================================== -First select the "Emscripten" configuration from the Configuration Manager dropdown as the active configuration, and choose Build Solution (F7). +First select the **Emscripten** configuration from the *Configuration Manager* dropdown as the active configuration. Then choose **Build Solution** (F7). How to launch a project in a web browser from Visual Studio -================================================================================ +=========================================================== -To launch a project directly to a web browser from Visual Studio, right-click on the project to run, choose "Set as Startup Project", and select Start without Debugging (Ctrl+F5). This should launch the generated .html file to the browser you specified in EMCC\_WEBBROWSER\_EXE. A bug(?) in Visual Studio causes a "Executable for Debug Session" dialog to occasionally open up when you hit Ctrl+F5. This can be ignored by clicking Yes, then No, or simply by hitting Esc and then tapping Ctrl+F5 again. +To launch a project directly to a web browser from Visual Studio: -llvm-clang and Emscripten compiler settings can be edited for the project in the "usual" Visual Studio fashion: First make sure that the Emscripten platform configuration is active, then right-click on a project, and choose Properties. In the Project properties dialog, two -tree nodes Clang C/C++ and Emcc Linker should exist, which allow you to specify the desired compilation options. +#. Create a new environment variable ``EMCC_WEBBROWSER_EXE`` and set it to point to an executable you want to use to browse web pages generated using Emscripten via Visual Studio. Any browser can be used — below we specify *Mozilla Firefox*: -If you have an existing solution file you want to build using Emscripten, open the Configuration Manager.. dialog for the solution, and in the Active Solution Platform dropdown, choose New.... In the new dialog, choose Emscripten as the platform name, and Copy settings from -Empty. After this, you can switch between building the solution for Win32 and Emscripten from the Configuration Manager dropdown list. + :: -When you want to create a new Visual Studio project for Emscripten, we recommend you start with a Visual C++ Empty Project. This will create a new project for the Win32 platform. Then convert that project for Emscripten as outlined in the previous paragraph. + SETX EMCC_WEBBROWSER_EXE C:/Program Files (x86)/Mozilla Firefox/firefox.exe - \ No newline at end of file +#. Right-click on the project to run, choose **Set as Startup Project**, and select **Start without Debugging** (**Ctrl+F5**). + +This should launch the generated **.html** file to the browser you specified in ``EMCC_WEBBROWSER_EXE``. + +.. note:: Visual Studio occasionally opens a "Executable for Debug Session" dialog when you hit **Ctrl+F5**. This can be ignored by clicking **Yes** and then **No**, or simply by hitting **Esc** and then tapping **Ctrl+F5** again. + + +Specifying project compiler settings +==================================== + +:ref:`Fastcomp ` (Clang+LLVM) and :ref:`Emscripten compiler ` settings can be edited for the project in exactly the same way as other settings in Visual Studio. First make sure that the Emscripten platform configuration is active, right-click on a project, and then choose **Properties** to open the *Project properties* dialog. + +The Project Properties should contain two tree nodes: *Clang C/C++* and *Emcc Linker*. These allow you to specify the desired compilation options. + +.. _getting-started-emscripten-vs-existing-solution: + +Porting an existing solution file to use Emscripten +=================================================== + +To add Emscripten as a build option for an existing project: + +#. Open the *Configuration Manager* dialog for the solution. +#. In the *Active Solution Platform* dropdown, choose **New**. +#. In the *New* dialog, choose **Emscripten** as the platform name, and **Copy settings from Empty**. + +Now you should be able to switch between building the solution for Win32 and Emscripten by selecting the desired option from the *Configuration Manager* dropdown list. + + +Creating a new Visual Studio solution for Emscripten +==================================================== + +To create a new Visual Studio project for Emscripten, first create a **Visual C++ Empty Project** (a new project for the Win32 platform). Then convert that project to also build for Emscripten as outlined in the previous section: :ref:`getting-started-emscripten-vs-existing-solution`. + \ No newline at end of file From 99d9ec802bd4c1df1a2cd748ab6da36e220c1bb4 Mon Sep 17 00:00:00 2001 From: hamishwillee Date: Sat, 23 Aug 2014 08:45:22 +1000 Subject: [PATCH 31/60] general fixes to FAQ and some of the getting started articles --- ...lly_integrating_emscripten_with_vs2010.rst | 7 +- .../verify_emscripten_environment.rst | 6 +- site/source/docs/getting_started/FAQ.rst | 220 ++++++++++-------- ...ing_started_with_emscripten_and_vs2010.rst | 67 ++++-- 4 files changed, 186 insertions(+), 114 deletions(-) diff --git a/site/source/docs/building_from_source/manually_integrating_emscripten_with_vs2010.rst b/site/source/docs/building_from_source/manually_integrating_emscripten_with_vs2010.rst index 2490bd3568c40..9c7012bbefc6e 100644 --- a/site/source/docs/building_from_source/manually_integrating_emscripten_with_vs2010.rst +++ b/site/source/docs/building_from_source/manually_integrating_emscripten_with_vs2010.rst @@ -32,8 +32,11 @@ Install the vs-tool plugin #. Set up the required environment variables for *vs-tool*. - #. Windows 7: Open **Control Panel | System | Advanced System Settings | Environment Variables**. - #. Windows 8: Right click on the **Windows menu icon | System | Advanced System Settings | Environment Variables**. + #. Open the Environment Variables setting: + + - Windows 7: Open **Control Panel | System | Advanced System Settings | Environment Variables**. + - Windows 8: Right click on the **Windows menu icon | System | Advanced System Settings | Environment Variables**. + #. Create a new environment variable ``CLANG_BIN`` and set it to point to the folder where you built *Fastcomp* (path to **clang.exe**) E.g.: :: diff --git a/site/source/docs/building_from_source/verify_emscripten_environment.rst b/site/source/docs/building_from_source/verify_emscripten_environment.rst index 53b5091a567ab..51e3852da02fe 100644 --- a/site/source/docs/building_from_source/verify_emscripten_environment.rst +++ b/site/source/docs/building_from_source/verify_emscripten_environment.rst @@ -43,9 +43,11 @@ At this point you need to :ref:`Install and activate ` are known to build and pass on the **master** branch, so it is likely that there is some problem with your environment. -- **Q.** I get lots of errors building the tests or even simple hello world type stuff? +First call ``./emcc -v``, which runs basic sanity checks and prints out useful environment information. If that doesn't help, follow the instructions in :ref:`verifying-the-emscripten-environment`. - **A.** Try to run ``emcc -v``, which prints out some helpful information and runs some sanity checks. You can also try ``emcc --clear-cache`` to empty the compiler's internal cache, which will then be rebuilt next time it is used. If none of those help or give an idea of what could be the matter, then some common problems to check for are: +You might also want to go through the :ref:`Tutorial` again, as this is updated as Emscripten changes. - - Typos in the paths in ``~/.emscripten``. - - Using older versions of Node or JS engines. Use the versions mentioned in the :ref:`Tutorial`. - - Using older versions of LLVM. See the :ref:`Emscripten-SDK` page for which version of LLVM is supported. Using other builds might not work. If you are using fastcomp, see :ref:`LLVM-Backend` for the proper repos for LLVM and clang that you should be using. - - Not having ``python2`` in your system. For compatibility with systems that install python 2.x alongside 3.x (increasingly common), we look for ``python2``. If you only have python 2.x installed, make ``python2`` be a link to ``python``. Or, instead you can invoke our python scripts directly, for example - ``python emcc`` instead of ``./emcc``. - You might also want to go through the :ref:`Tutorial` again, if it's been a while since you have (we update it when things change). +I tried something and it doesn't work? +====================================== -- **Q.** I tried something and it doesn't work? +This site has comprehensive documentation. If you tried "something" and it fails (for example a :ref:`compiler flag `, or a *libc* function), one of the first options should therefore be to search the site. - **A.** Emscripten has an extensive test suite. If you try something (a compiler flag, a libc function, etc.) and it fails, often the best thing is to ``grep -r`` in ``tests/`` to see if there is a test for it. On the master branch, **all** tests are known to pass. The tests can therefore both show you what works, and also they give concrete examples for how to use things, which can be helpful in addition to the docs. +Another really good option is to see if there is a test for the failing functionality in the :ref:`Emscripten test suite ` (run ``grep -r`` in ``tests/``). **All** the tests are known to pass on the master branch, so they provide concrete "known-good" examples of how various options and code are used. -- **Q.** Can I compile my project using Emscripten? Do I need a new build system? - **A.** You can in most cases very easily use your project's current build system with Emscripten. See :ref:`Building-Projects`. +Do I need to change my build system to use Emscripten? +====================================================== -- **Q.** My code cannot access a file that is right there in the same directory? +In most cases you will be able to use your project's current build system with Emscripten. See :ref:`Building-Projects`. - **A.** Emscripten-generated code cannot by default access local files on your machine like a native application. See :ref:`Filesystem-Guide` - for details: you can in node allow such access, and in other platforms you can use preloading to work around lack of synchronous file IO. -- **Q.** My code compiles slowly. +My code cannot access a file in the same directory? +=================================================== - **A.** Emscripten makes some tradeoffs that make the generated code faster and smaller, at the cost of longer compilation times. For example, we build parts of the standard library along with your code which enables some additional optimizations, but takes a little longer to compile. +Emscripten-generated code cannot by default access local files on your machine like a native application. See :ref:`Filesystem-Guide` for details: you can in node allow such access, and in other platforms you can use preloading to work around lack of synchronous file IO. - Emscripten can run some passes in parallel (specifically, the JS opts), and will do so automatically, so running on a machine with more cores can give you almost a linear speedup (so doubling the amount of cores can almost halve the amount of time it takes to build and so forth). To see details of how work is parallelized, compile with ``EMCC_DEBUG=1`` in the environment (note though that in that debug mode compilation takes longer than normal, because we print out a lot of intermediate steps to disk, by default to ``/tmp/emscripten_temp``, but it's still useful to see which stages are slowing you down). You can affect how many cores are using with ``EMCC_CORES=N``, which can be useful if you have many cores but relatively less memory. - Note that optimization can in some cases be noticeably slower than unoptimized code, ``-O1`` is slower than ``-O0``, which in turn is slower than ``-O2`` (in return, though, they greatly improve the speed of the generated code). It might be useful to use ``-O0`` (or not specify an optimization level) during quick development iterations and to do fully optimized builds less frequently. Note that ``-O3`` is **especially** slow (you can mitigate the ``-O3`` slowness by also enabling ``-s AGGRESSIVE_VARIABLE_ELIMINATION=1``, as it removes variables which makes the ``-O3`` regalloc easier). +My code compiles slowly. +======================== - Currently builds with line-number debug info (where the source code was compiled with ``-g``) are slow, see issue #216. Stripping the debug info leads to much faster compile times. +Emscripten makes some tradeoffs that make the generated code faster and smaller, at the cost of longer compilation times. For example, we build parts of the standard library along with your code which enables some additional optimizations, but takes a little longer to compile. -- **Q.** My code runs slowly. +Emscripten can run some passes in parallel (specifically, the JS opts), and will do so automatically, so running on a machine with more cores can give you almost a linear speedup (so doubling the amount of cores can almost halve the amount of time it takes to build and so forth). To see details of how work is parallelized, compile with ``EMCC_DEBUG=1`` in the environment (note though that in that debug mode compilation takes longer than normal, because we print out a lot of intermediate steps to disk, by default to ``/tmp/emscripten_temp``, but it's still useful to see which stages are slowing you down). You can affect how many cores are using with ``EMCC_CORES=N``, which can be useful if you have many cores but relatively less memory. - **A.** Make sure you build with ``-O2`` so code is optimized. **This is necessary both for each source file, and for the final stage of linking and compiling to JS**, see more details :ref:`Building-Projects`. See :ref:`Optimizing-Code` for more info. +Note that optimization can in some cases be noticeably slower than unoptimized code, ``-O1`` is slower than ``-O0``, which in turn is slower than ``-O2`` (in return, though, they greatly improve the speed of the generated code). It might be useful to use ``-O0`` (or not specify an optimization level) during quick development iterations and to do fully optimized builds less frequently. Note that ``-O3`` is **especially** slow (you can mitigate the ``-O3`` slowness by also enabling ``-s AGGRESSIVE_VARIABLE_ELIMINATION=1``, as it removes variables which makes the ``-O3`` regalloc easier). -- **Q.** My code is large. +Currently builds with line-number debug info (where the source code was compiled with ``-g``) are slow, see issue #216. Stripping the debug info leads to much faster compile times. - **A.** Make sure you build with ``-O2`` so code is optimized, which includes minification to reduce size. You should also set up gzip compression on your webserver, which all browsers now support. - You can use closure compile to reduce code size even more with ``--closure 1``, however that will require that your code with with closure compiler advanced optimizations, including proper exports and so forth. It is usually not worth the effort over an optimized build+server gzip. +My code runs slowly. +===================== -- **Q.** When I compile code that should work, I get odd errors in Emscripten about various things. I get different errors (or it works) on another machine. +Make sure you build with ``-O2`` so code is optimized. **This is necessary both for each source file, and for the final stage of linking and compiling to JS**, see more details :ref:`Building-Projects`. See :ref:`Optimizing-Code` for more info. - **A.** Make sure you are using the Emscripten bundled system headers. Using ``emcc`` will do so by default, but if you compile into LLVM bitcode yourself, or you use your local system headers even with ``emcc``, problems can happen. -- **Q.** My large codebase runs ok, but the time it takes to start up is significant. What can I do to improve that? +My code is large. +=========================== - **A.** First, make sure you are running an optimized build (which will be much smaller and faster to start up). Then, if the sheer code size is causing the slow startup, you can try the `outlining option in emscripten `__. +Make sure you build with ``-O2`` so code is optimized, which includes minification to reduce size. You should also set up gzip compression on your webserver, which all browsers now support. - Another possible factor is network latency. If you load data off the network and also have a big codebase, try to put the file loading code in a separate script element - that is, run the file packager (``tools/file_packager.py``) and put its code in one script element, and in another script element after it put the generated codebase. That will allow the browser to start the network download immediately, so it can run in parallel to the browser parsing and starting up the codebase. +You can use closure compile to reduce code size even more with ``--closure 1``, however that will require that your code with with closure compiler advanced optimizations, including proper exports and so forth. It is usually not worth the effort over an optimized build+server gzip. -- **Q.** My code fails to compile, the error includes something about inline assembly (or ``{"text":"asm"}``). - **A.** Emscripten cannot compile inline assembly code, which is CPU specific, because Emscripten is not a CPU emulator. +When I compile code that should work, I get odd errors in Emscripten about various things. I get different errors (or it works) on another machine. +========================================================================================================================================================================== - Many projects have build options that generate only platform-independent code, without inline assembly. That should be used for Emscripten. For example, the following might help (and are done automatically for you by ``emcc``): +Make sure you are using the Emscripten bundled system headers. Using ``emcc`` will do so by default, but if you compile into LLVM bitcode yourself, or you use your local system headers even with ``emcc``, problems can happen. + + +My large codebase runs ok, but the time it takes to start up is significant. What can I do to improve that? +======================================================================================================================================== + +First, make sure you are running an optimized build (which will be much smaller and faster to start up). Then, if the sheer code size is causing the slow startup, you can try the `outlining option in emscripten `__. + +Another possible factor is network latency. If you load data off the network and also have a big codebase, try to put the file loading code in a separate script element - that is, run the file packager (``tools/file_packager.py``) and put its code in one script element, and in another script element after it put the generated codebase. That will allow the browser to start the network download immediately, so it can run in parallel to the browser parsing and starting up the codebase. + + +My code fails to compile, the error includes something about inline assembly (or ``{"text":"asm"}``). +======================================================================================================================================== + +Emscripten cannot compile inline assembly code, which is CPU specific, because Emscripten is not a CPU emulator. + +Many projects have build options that generate only platform-independent code, without inline assembly. That should be used for Emscripten. For example, the following might help (and are done automatically for you by ``emcc``): :: #undef __i386__ #undef __x86_64__ - Since when no CPU-specific ``#define`` exists, many projects will not generate CPU specific code. In general though, you will need to find where inline assembly is generated, and how to disable that. +Since when no CPU-specific ``#define`` exists, many projects will not generate CPU specific code. In general though, you will need to find where inline assembly is generated, and how to disable that. + + +How do I run an event loop? +=========================== -- **Q.** How do I run an event loop? +To run a C function repeatedly, use :c:func:`emscripten_set_main_loop` (**emscripten.h**). The other functions in that file are also useful, they let you do things like add events that block the main loop, etc. - **A.** To run a C function repeatedly, use :c:func:`emscripten_set_main_loop` (**emscripten.h**). The other functions in that file are also useful, they let you do things like add events that block the main loop, etc. +To respond to browser events and so forth, use the SDL API normally. See the SDL tests for examples (look for SDL in ``tests/runner.py``). - To respond to browser events and so forth, use the SDL API normally. See the SDL tests for examples (look for SDL in ``tests/runner.py``). +See also the next question. - See also the next question. -- **Q.** My HTML app hangs. +My HTML app hangs. +================== **A.** Graphical C++ apps typically have a main loop that is an infinite loop, in which event handling is done, processing and rendering, then SDL_Delay. However, in JS there is no way for SDL_Delay to actually return control to the browser event loop. To do that, you must exit the current code. See :ref:`Emscripten-Browser-Environment`. -- **Q.** My SDL app doesn't work. +My SDL app doesn't work. +======================== - **A.** See the SDL automatic tests for working examples: ``python tests/runner.py browser``. +See the SDL automatic tests for working examples: ``python tests/runner.py browser``. -- **Q.** How do I link against system libraries like SDL, boost, etc.? +How do I link against system libraries like SDL, boost, etc.? +================================================================== - **A.** System libraries that are included with emscripten - libc, libc++ (C++ standard library) and SDL - are automatically included when you compile (and just the necessary parts of them). You don't even need ``-lSDL``, unlike other compilers (but ``-lSDL`` won't hurt either). +System libraries that are included with Emscripten - libc, libc++ (C++ standard library) and SDL - are automatically included when you compile (and just the necessary parts of them). You don't even need ``-lSDL``, unlike other compilers (but ``-lSDL`` won't hurt either). - Other libraries not included with emscripten, like boost, you would need to compile yourself and link with your program, just as if they were a module in your project. For example, see how `BananaBread links in libz `_. - (Note that in the specific case of boost, if you only need the boost headers, you don't need to compile anything.) +Other libraries not included with Emscripten, like boost, you would need to compile yourself and link with your program, just as if they were a module in your project. For example, see how `BananaBread links in libz `_. (Note that in the specific case of boost, if you only need the boost headers, you don't need to compile anything.) - Another option for libraries not included is to implement them as a JS library, like emscripten does for libc (minus malloc) and SDL (but not libc++ or malloc). See ``--js-library`` in emcc. +Another option for libraries not included is to implement them as a JS library, like emscripten does for libc (minus malloc) and SDL (but not libc++ or malloc). See ``--js-library`` in emcc. -- **Q.** How can my compiled program access files? - **A.** Emscripten uses a virtual file system that may be preloaded with data or linked to URLs for lazy loading. See the :ref:`Filesystem-Guide` for more details. +How can my compiled program access files? +================================================================== -- **Q.** Functions in my C/C++ source code vanish when I compile to JavaScript, and/or I get ``No functions to process``..? +Emscripten uses a virtual file system that may be preloaded with data or linked to URLs for lazy loading. See the :ref:`Filesystem-Guide` for more details. + + +Functions in my C/C++ source code vanish when I compile to JavaScript, and/or I get ``No functions to process``..? +================================================================================================================== **A.** By default Emscripten does dead code elimination to minimize code size. However, it might end up removing functions you want to call yourself, that are not called from the compiled code (so the LLVM optimizer thinks they are unneeded). You can run emcc with ``-s LINKABLE=1`` which will disable link-time optimizations and dead code elimination, but this makes the code larger and less optimized than it could be. Instead, you should prevent specific functions from being eliminated by adding them to EXPORTED_FUNCTIONS (see ``src/settings.js``), for example, run emcc with something like ``-s EXPORTED_FUNCTIONS="['_main', '_my_func']"`` in order to keep my_func from being removed/renamed (as well as ``main()``)). Note that this assumes my_func is a C function, otherwise you would need to write out the C++ name mangling. @@ -124,69 +148,83 @@ FAQ (wiki-import) Note: In LLVM 3.2 dead code elimination is significantly more aggressive. All functions not kept alive through EXPORTED_FUNCTIONS will be potentially eliminated. Make sure to keep the things you need alive using one or both of those methods. -- **Q.** The FS API is not available when I build with closure? - - **A.** Closure compiler will minify the FS API code. To write code that uses it, it must be optimized **with** the FS API code by closure. To do that, use emcc's ``--pre-js`` option, see ``emcc --help``. +The FS API is not available when I build with closure? +======================================================= -- **Q.** My code breaks with ``-O2 --closure 1``, giving odd errors..? +Closure compiler will minify the FS API code. To write code that uses it, it must be optimized **with** the FS API code by closure. To do that, use emcc's ``--pre-js`` option, see ``emcc --help``. - **A.** The likely problem is that Closure Compiler minifies variable names. Names like ``i,j,xa`` can be generated, and if other code has such variables in the global scope, bad things can happen. - To check if this is the problem, compile with ``-O2`` (without ``--closure 1``). If that works, name minification might be the problem. If so, wrapping the generated code in a closure should fix it. (Or, wrap your other code in a closure, or stop it from using small variable names in the global scope, you might be using such variables by mistake by forgetting a ``var`` and assigning to a variable - which makes it be in the global scope.) +My code breaks with ``-O2 --closure 1``, giving odd errors..? +==================================================================== - To 'wrap' code in a closure, do something like this: +The likely problem is that Closure Compiler minifies variable names. Names like ``i,j,xa`` can be generated, and if other code has such variables in the global scope, bad things can happen. + +To check if this is the problem, compile with ``-O2`` (without ``--closure 1``). If that works, name minification might be the problem. If so, wrapping the generated code in a closure should fix it. (Or, wrap your other code in a closure, or stop it from using small variable names in the global scope, you might be using such variables by mistake by forgetting a ``var`` and assigning to a variable - which makes it be in the global scope.) + +To 'wrap' code in a closure, do something like this: :: - var CompiledModule = (function() { - .. GENERATED CODE .. - return Module; - })(); + var CompiledModule = (function() { + .. GENERATED CODE .. + return Module; + })(); -- **Q.** I get ``undefined is not a function`` or ``NAME is not a function``..? +I get ``undefined is not a function`` or ``NAME is not a function``..? +===================================================================================== - **A.** The likely cause is an undefined function - something that was referred to, but not implemented or linked in. If you get ``undefined``, look at the line number to see the function name. +The likely cause is an undefined function - something that was referred to, but not implemented or linked in. If you get ``undefined``, look at the line number to see the function name. - Emscripten by default does *not* give fatal errors on undefined symbols, so you can get runtime errors like these (because in practice in many codebases it is easiest to get them working without refactoring them to remove all undefined symbol calls). If you prefer compile-time notifications, run emcc with - ``-s WARN_ON_UNDEFINED_SYMBOLS=1`` or ``-s ERROR_ON_UNDEFINED_SYMBOLS=1``. +Emscripten by default does *not* give fatal errors on undefined symbols, so you can get runtime errors like these (because in practice in many codebases it is easiest to get them working without refactoring them to remove all undefined symbol calls). If you prefer compile-time notifications, run emcc with ``-s WARN_ON_UNDEFINED_SYMBOLS=1`` or ``-s ERROR_ON_UNDEFINED_SYMBOLS=1``. - Aside from just forgetting to link in a necessary object file, one possible cause for this error is inline functions in headers. If you have a header with ``inline int my_func() { .. }`` then clang may not actually inline the function (since inline is just a hint), and also not generate code for it (since it's in a header), so the generated bitcode and js will not have that function implemented. One solution is to add ``static``, that is ``static inline int my_func() { .. }`` which forces code to be generated in the object file. +Aside from just forgetting to link in a necessary object file, one possible cause for this error is inline functions in headers. If you have a header with ``inline int my_func() { .. }`` then clang may not actually inline the function (since inline is just a hint), and also not generate code for it (since it's in a header), so the generated bitcode and js will not have that function implemented. One solution is to add ``static``, that is ``static inline int my_func() { .. }`` which forces code to be generated in the object file. -- **Q.** I get an odd python error complaining about libcxx.bc or libcxxabi.bc..? +I get an odd python error complaining about libcxx.bc or libcxxabi.bc..? +===================================================================================== - **A.** Possibly building libcxx or libcxxabi failed. Go to system/lib/libcxx (or libcxxabi) and do ``emmake make`` to see the actual error. Or, clean the emscripten cache (``~/.emscripten_cache``) and then compile your file with ``EMCC_DEBUG=1`` in the environment. libcxx will then be built in + +Possibly building libcxx or libcxxabi failed. Go to system/lib/libcxx (or libcxxabi) and do ``emmake make`` to see the actual error. Or, clean the emscripten cache (``~/.emscripten_cache``) and then compile your file with ``EMCC_DEBUG=1`` in the environment. libcxx will then be built in ``/tmp/emscripten_temp/libcxx``, and you can see ``configure*,make*`` files that are the output of configure and make, etc. - One possible cause of this error is the lack of ``make``, which is necessary to build these libraries. If you are on Windows, you need cygwin which supplies ``make``. +One possible cause of this error is the lack of ``make``, which is necessary to build these libraries. If you are on Windows, you need cygwin which supplies ``make``. + +Running LLVM bitcode generated by emcc through ``lli`` breaks with errors about ``impure_ptr`` stuff..? +======================================================================================================== -- **Q.** Running LLVM bitcode generated by emcc through ``lli`` breaks with errors about ``impure_ptr`` stuff..? +First of all, lli is not maintained (sadly) and has odd errors and crashes. However there is ``tools/nativize_llvm.py`` which compiles bitcode to a native executable. It will also hit the ``impure_ptr`` error though. - **A.** First of all, lli is not maintained (sadly) and has odd errors and crashes. However there is ``tools/nativize_llvm.py`` which compiles bitcode to a native executable. It will also hit the ``impure_ptr`` error though. +The issue is that newlib uses that impure pointer stuff, while glibc uses something else. So bitcode build with the emscripten SDK (which emcc does) will not run locally, unless your machine uses newlib (which basically only embedded systems do). The impure_ptr stuff is limited, however, it only applies to explicit use of ``stdout`` etc. So ``printf(..)`` will work, but ``fprintf(stdout, ..)`` will not. So often it is simple to modify your code to not hit this problem. - The issue is that newlib uses that impure pointer stuff, while glibc uses something else. So bitcode build with the emscripten SDK (which emcc does) will not run locally, unless your machine uses newlib (which basically only embedded systems do). The impure_ptr stuff is limited, however, it only applies to explicit use of ``stdout`` etc. So ``printf(..)`` will work, but ``fprintf(stdout, ..)`` will not. So often it is simple to modify your code to not hit this problem. +I get a stack size error when optimizing (``RangeError: Maximum call stack size exceeded`` or similar)? +======================================================================================================================================= -- **Q.** I get a stack size error when optimizing (``RangeError: Maximum call stack size exceeded`` or similar)? +You may need to increase the stack size for node. On linux and mac, you can just do ``NODE_JS = ['node', '--stack_size=8192']`` or such (in ``~/.emscripten``). On windows, you will also need ``--max-stack-size=8192``, and also to run ``editbin /stack:33554432 node.exe``. - **A.** You may need to increase the stack size for node. On linux and mac, you can just do ``NODE_JS = ['node', '--stack_size=8192']`` or such (in ``~/.emscripten``). On windows, you will also need ``--max-stack-size=8192``, and also to run ``editbin /stack:33554432 node.exe``. -- **Q.** I get ``error: cannot compile this aggregate va_arg expression yet`` and it says ``compiler frontend failed to generate LLVM bitcode, halting`` afterwards. +I get ``error: cannot compile this aggregate va_arg expression yet`` and it says ``compiler frontend failed to generate LLVM bitcode, halting`` afterwards. +============================================================================================================================================================================================= - **A.** This is a limitation of the le32 frontend in clang. You can use the x86 frontend instead by compiling with ``EMCC_LLVM_TARGET=i386-pc-linux-gnu`` in the environment (however you will lose the advantages of le32 which includes better alignment of doubles). +This is a limitation of the le32 frontend in clang. You can use the x86 frontend instead by compiling with ``EMCC_LLVM_TARGET=i386-pc-linux-gnu`` in the environment (however you will lose the advantages of le32 which includes better alignment of doubles). .. _faq-when-safe-to-call-compiled-functions: -- **Q.** I am building a library, and sometimes I get an error when I call a compiled function before the page fully loaded. How can I tell when is safe to call it? +I am building a library, and sometimes I get an error when I call a compiled function before the page fully loaded. How can I tell when is safe to call it? +============================================================================================================================================================================ - **A.** The easiest way to find out when loading is complete (which is asynchronous, as it often requires loading files, such as the .mem file or preloade files), is to just add a ``main()`` function. It will be called when it is safe to do so, after startup is complete, so that is a signal that it is safe to call any compiled method. - You can make ``main()`` call your JS to notify it, for example if ``allReady()`` is a JS function you want called when everything is ready, you can do +The easiest way to find out when loading is complete (which is asynchronous, as it often requires loading files, such as the .mem file or preloade files), is to just add a ``main()`` function. It will be called when it is safe to do so, after startup is complete, so that is a signal that it is safe to call any compiled method. - :: +You can make ``main()`` call your JS to notify it, for example if ``allReady()`` is a JS function you want called when everything is ready, you can do + +:: + + #include - #include - int main() { - EM_ASM( allReady() ); - } + int main() { + EM_ASM( allReady() ); + } -- **Q.** The name of the project sounds weird to me. + +The name of the project sounds weird to me +========================================== - **A.** I don't know why; it's a perfectly `cromulent `_ word! +I don't know why; it's a perfectly `cromulent `_ word! diff --git a/site/source/docs/getting_started/getting_started_with_emscripten_and_vs2010.rst b/site/source/docs/getting_started/getting_started_with_emscripten_and_vs2010.rst index c958c2cba5ca0..7be256352e598 100644 --- a/site/source/docs/getting_started/getting_started_with_emscripten_and_vs2010.rst +++ b/site/source/docs/getting_started/getting_started_with_emscripten_and_vs2010.rst @@ -1,40 +1,69 @@ -.. _getting-started-emscripten-from-vs2010: +.. _getting-started-emscripten-from-visual-studio: -=========================================================================================== -Getting started using Emscripten from the Visual Studio 2010 IDE (under-construction) -=========================================================================================== +====================================================================== +Getting started using Emscripten from Visual Studio (ready-for-review) +====================================================================== -Windows Developers who want to use an IDE can develop and compile their Emscripten projects from `Microsoft Visual Studio 2010 `_. This article shows you how. +Windows Developers can develop, compile, and launch, their Emscripten projects from `Microsoft Visual Studio 2010 `_ (only). This topic shows you how. -.. note:: Visual Studio 2011 and 2012 are not supported. +.. warning:: Visual Studio 2011 and 2012 are not supported. Integrating Emscripten and Visual Studio ======================================== -The integration is enabled the :term:`vs-tool` plugin. +Emscripten is integrated into Visual Studio (2010) using the :term:`vs-tool` plugin, which is is automatically deployed by the :term:`Windows NSIS Installer Emscripten SDK` if *Visual Studio 2010* is present on your system at install time (it is also possible to :ref:`manually integrate Emscripten into Visual Studio 2010 `). -This plugin is automatically deployed by the :term:`Windows NSIS Installer Emscripten SDK` if *Visual Studio 2010* is present on your system. It is also possible to :ref:`manually integrate Emscripten into Visual Studio 2010 `. +The *vs-tool* plugin adds an **Emscripten** configuration to the list of available *Solution Configurations* in Visual Studio. Activate this configuration for a solution/project to make Visual Studio run the project build through Emscripten, producing **.html** or **.js** output depending on the configured project properties. -The *vs-tool* plugin adds an 'Emscripten' configuration to the list of available *Solution Configurations* in Visual Studio. Activate this configuration for a solution/project to make Visual Studio run the project build through Emscripten, producing **.html** or **.js** output depending on the configured project properties. How to build a Visual Studio solution using Emscripten -================================================================================ +====================================================== -First select the "Emscripten" configuration from the Configuration Manager dropdown as the active configuration, and choose Build Solution (F7). +First select the **Emscripten** configuration from the *Configuration Manager* dropdown as the active configuration. Then choose **Build Solution** (F7). How to launch a project in a web browser from Visual Studio -================================================================================ +=========================================================== -To launch a project directly to a web browser from Visual Studio, right-click on the project to run, choose "Set as Startup Project", and select Start without Debugging (Ctrl+F5). This should launch the generated .html file to the browser you specified in EMCC\_WEBBROWSER\_EXE. A bug(?) in Visual Studio causes a "Executable for Debug Session" dialog to occasionally open up when you hit Ctrl+F5. This can be ignored by clicking Yes, then No, or simply by hitting Esc and then tapping Ctrl+F5 again. +To launch a project directly to a web browser from Visual Studio: -llvm-clang and Emscripten compiler settings can be edited for the project in the "usual" Visual Studio fashion: First make sure that the Emscripten platform configuration is active, then right-click on a project, and choose Properties. In the Project properties dialog, two -tree nodes Clang C/C++ and Emcc Linker should exist, which allow you to specify the desired compilation options. +#. Create a new environment variable ``EMCC_WEBBROWSER_EXE`` and set it to point to an executable you want to use to browse web pages generated using Emscripten via Visual Studio. Any browser can be used — below we specify *Mozilla Firefox*: -If you have an existing solution file you want to build using Emscripten, open the Configuration Manager.. dialog for the solution, and in the Active Solution Platform dropdown, choose New.... In the new dialog, choose Emscripten as the platform name, and Copy settings from -Empty. After this, you can switch between building the solution for Win32 and Emscripten from the Configuration Manager dropdown list. + :: -When you want to create a new Visual Studio project for Emscripten, we recommend you start with a Visual C++ Empty Project. This will create a new project for the Win32 platform. Then convert that project for Emscripten as outlined in the previous paragraph. + SETX EMCC_WEBBROWSER_EXE C:/Program Files (x86)/Mozilla Firefox/firefox.exe - \ No newline at end of file +#. Right-click on the project to run, choose **Set as Startup Project**, and select **Start without Debugging** (**Ctrl+F5**). + +This should launch the generated **.html** file to the browser you specified in ``EMCC_WEBBROWSER_EXE``. + +.. note:: Visual Studio occasionally opens a "Executable for Debug Session" dialog when you hit **Ctrl+F5**. This can be ignored by clicking **Yes** and then **No**, or simply by hitting **Esc** and then tapping **Ctrl+F5** again. + + +Specifying project compiler settings +==================================== + +:ref:`Fastcomp ` (Clang+LLVM) and :ref:`Emscripten compiler ` settings can be edited for the project in exactly the same way as other settings in Visual Studio. First make sure that the Emscripten platform configuration is active, right-click on a project, and then choose **Properties** to open the *Project properties* dialog. + +The Project Properties should contain two tree nodes: *Clang C/C++* and *Emcc Linker*. These allow you to specify the desired compilation options. + +.. _getting-started-emscripten-vs-existing-solution: + +Porting an existing solution file to use Emscripten +=================================================== + +To add Emscripten as a build option for an existing project: + +#. Open the *Configuration Manager* dialog for the solution. +#. In the *Active Solution Platform* dropdown, choose **New**. +#. In the *New* dialog, choose **Emscripten** as the platform name, and **Copy settings from Empty**. + +Now you should be able to switch between building the solution for Win32 and Emscripten by selecting the desired option from the *Configuration Manager* dropdown list. + + +Creating a new Visual Studio solution for Emscripten +==================================================== + +To create a new Visual Studio project for Emscripten, first create a **Visual C++ Empty Project** (a new project for the Win32 platform). Then convert that project to also build for Emscripten as outlined in the previous section: :ref:`getting-started-emscripten-vs-existing-solution`. + \ No newline at end of file From 2d7a7ec3308a378c8ebaac1254b37dcaa5496208 Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Fri, 22 Aug 2014 16:11:11 -0700 Subject: [PATCH 32/60] remove some unnecessary trailing commas --- src/modules.js | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/modules.js b/src/modules.js index 3db6663c02bdd..cdcc157f560b2 100644 --- a/src/modules.js +++ b/src/modules.js @@ -436,12 +436,12 @@ var LibraryManager = { 'library_memfs.js', 'library_nodefs.js', 'library_sockfs.js', - 'library_tty.js', + 'library_tty.js' ]); } if (!NO_BROWSER) { libraries = libraries.concat([ - 'library_browser.js', + 'library_browser.js' ]); } libraries = libraries.concat([ From 0dafe7f5f7f00fa4daa8e42271a0dfdec8687856 Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Fri, 22 Aug 2014 16:24:09 -0700 Subject: [PATCH 33/60] clarify returnType for ccall/cwrap; fixes #2705 --- site/build/text/docs/api_reference/preamble.js.txt | 13 ++++++++----- site/source/docs/api_reference/preamble.js.rst | 2 +- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/site/build/text/docs/api_reference/preamble.js.txt b/site/build/text/docs/api_reference/preamble.js.txt index 68514c19ac584..6e7f203a35bca 100644 --- a/site/build/text/docs/api_reference/preamble.js.txt +++ b/site/build/text/docs/api_reference/preamble.js.txt @@ -8,7 +8,7 @@ functions, accessing memory, converting pointers to JavaScript "Strings" and "Strings" to pointers (with different encodings/formats), and other convenience functions. -Note: All functions should be called though the "Module" object (for +Note: All functions should be called though the *Module* object (for example: "Module.functionName"). At optimisation "-O2" (and higher) function names are minified by the closure compiler, and calling them directly will fail. @@ -76,10 +76,13 @@ ccall(ident, returnType, argTypes, args) Arguments: * **ident** -- The name of the C function to be called. - * **returnType** -- The return type of the function. This will - be one of the JavaScript types "number", "string" or "array" - (use "number" for any C pointer, and "array" for JavaScript - arrays and typed arrays; note that arrays are 8-bit). + * **returnType** -- The return type of the function. This can + be ""number"", ""string"" or ""array"", which correspond to + the appropriate JavaScript types (use ""number"" for any C + pointer, and ""array"" for JavaScript arrays and typed arrays; + note that arrays are 8-bit), or for a void function it can be + "null" (note: the JavaScript "null" value, not a string + containing the word "null"). * **argTypes** -- An array of the types of arguments for the function (if there are no arguments, this can be omitted). diff --git a/site/source/docs/api_reference/preamble.js.rst b/site/source/docs/api_reference/preamble.js.rst index 1da8db591d808..4291093a2ee23 100644 --- a/site/source/docs/api_reference/preamble.js.rst +++ b/site/source/docs/api_reference/preamble.js.rst @@ -49,7 +49,7 @@ Calling compiled C functions from JavaScript :param ident: The name of the C function to be called. - :param returnType: The return type of the function. This will be one of the JavaScript types ``number``, ``string`` or ``array`` (use ``number`` for any C pointer, and ``array`` for JavaScript arrays and typed arrays; note that arrays are 8-bit). + :param returnType: The return type of the function. This can be ``"number"``, ``"string"`` or ``"array"``, which correspond to the appropriate JavaScript types (use ``"number"`` for any C pointer, and ``"array"`` for JavaScript arrays and typed arrays; note that arrays are 8-bit), or for a void function it can be ``null`` (note: the JavaScript ``null`` value, not a string containing the word "null"). :param argTypes: An array of the types of arguments for the function (if there are no arguments, this can be omitted). Types are as in ``returnType``, except that ``array`` is not supported as there is no way for us to know the length of the array). :param args: An array of the arguments to the function, as native JavaScript values (as in ``returnType``). Note that string arguments will be stored on the stack (the JavaScript string will become a C string on the stack). :returns: The result of the function call as a native JavaScript value (as in ``returnType``). From 50a38fecab6ae898777b73d659ed95bfd8813bb8 Mon Sep 17 00:00:00 2001 From: Jukka Jylanki Date: Sun, 24 Aug 2014 12:26:54 +0300 Subject: [PATCH 34/60] Pass -Wno-warn-absolute-paths when building libcxx and libcxxabi to avoid the spamming absolute path warnings on first time build, which could easily be confused as the compiler having hung in an infinite error loop, since there are hundreds of these messages being printed. --- tools/system_libs.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tools/system_libs.py b/tools/system_libs.py index c86650bce015d..51b06fe6499e7 100644 --- a/tools/system_libs.py +++ b/tools/system_libs.py @@ -405,7 +405,7 @@ def create_libcxx(): 'regex.cpp', 'strstream.cpp' ] - return build_libcxx(os.path.join('system', 'lib', 'libcxx'), 'libcxx.bc', libcxx_files, ['-Oz', '-I' + shared.path_from_root('system', 'lib', 'libcxxabi', 'include')]) + return build_libcxx(os.path.join('system', 'lib', 'libcxx'), 'libcxx.bc', libcxx_files, ['-Oz', '-Wno-warn-absolute-paths', '-I' + shared.path_from_root('system', 'lib', 'libcxxabi', 'include')]) def apply_libcxx(need): assert shared.Settings.QUANTUM_SIZE == 4, 'We do not support libc++ with QUANTUM_SIZE == 1' @@ -431,7 +431,7 @@ def create_libcxxabi(): 'private_typeinfo.cpp', os.path.join('..', '..', 'libcxx', 'new.cpp'), ] - return build_libcxx(os.path.join('system', 'lib', 'libcxxabi', 'src'), 'libcxxabi.bc', libcxxabi_files, ['-Oz', '-I' + shared.path_from_root('system', 'lib', 'libcxxabi', 'include')]) + return build_libcxx(os.path.join('system', 'lib', 'libcxxabi', 'src'), 'libcxxabi.bc', libcxxabi_files, ['-Oz', '-Wno-warn-absolute-paths', '-I' + shared.path_from_root('system', 'lib', 'libcxxabi', 'include')]) def apply_libcxxabi(need): assert shared.Settings.QUANTUM_SIZE == 4, 'We do not support libc++abi with QUANTUM_SIZE == 1' From 4f9c7121d25de3839958952c6e7cb078f58722c2 Mon Sep 17 00:00:00 2001 From: hamishwillee Date: Mon, 25 Aug 2014 21:00:23 +1000 Subject: [PATCH 35/60] Fixes as a result of feedback to Getting Started topics. Minor additions to number of other topics --- site/source/conf.py | 2 - .../docs/api_reference/emscripten.h.rst | 5 +- .../docs/coding/Browser-limitations.rst | 17 +- .../coding/CodeGuidelinesAndLimitations.rst | 61 +++-- .../source/docs/coding/Garbage_Collection.rst | 35 +-- .../docs/compiling/Code-Generation-Modes.rst | 22 +- site/source/docs/getting_started/FAQ.rst | 257 +++++++++++------- site/source/docs/getting_started/Tutorial.rst | 4 +- .../source/docs/getting_started/downloads.rst | 2 +- site/source/docs/getting_started/index.rst | 2 +- .../docs/packaging/Filesystem-Guide.rst | 2 + site/source/docs/site/about.rst | 31 +-- site/source/docs/tools_reference/emcc.rst | 14 +- site/source/docs/tools_reference/emsdk.rst | 1 + 14 files changed, 263 insertions(+), 192 deletions(-) diff --git a/site/source/conf.py b/site/source/conf.py index 0875078cb0309..65f934205fab2 100644 --- a/site/source/conf.py +++ b/site/source/conf.py @@ -397,5 +397,3 @@ # HamishW - Specify a default project: #breathe_default_project = "nutshell" -# Comment/uncomment the line below for normal/SDK builds. -#tags.add('sdkbuild') \ No newline at end of file diff --git a/site/source/docs/api_reference/emscripten.h.rst b/site/source/docs/api_reference/emscripten.h.rst index 9c048884efe42..dd8bacaf2c0af 100644 --- a/site/source/docs/api_reference/emscripten.h.rst +++ b/site/source/docs/api_reference/emscripten.h.rst @@ -68,7 +68,7 @@ Calling JavaScript From C/C++ ============================= Function pointer types for callbacks -------------------------------------- +------------------------------------ The following types are used to define function callback signatures used in a number of functions in this file. @@ -159,9 +159,10 @@ Functions :rtype: void +.. _emscripten-h-browser-execution-environment: Browser Execution Environment -================================= +============================= Functions --------- diff --git a/site/source/docs/coding/Browser-limitations.rst b/site/source/docs/coding/Browser-limitations.rst index f980f99208c12..1eab100f62bf5 100644 --- a/site/source/docs/coding/Browser-limitations.rst +++ b/site/source/docs/coding/Browser-limitations.rst @@ -1,15 +1,14 @@ .. _Browser-limitations: -================================= -Browser limitations (wiki-import) -================================= -.. note:: This article was migrated from the wiki (Fri, 25 Jul 2014 04:21) and is now the "master copy" (the version in the wiki will be deleted). It may not be a perfect rendering of the original but we hope to fix that soon! +====================================== +Browser limitations (ready-for-review) +====================================== -This page collects together some of the most common differences between the latest versions of the major browsers and features that emscripten-based applications and games typically depend on. Use this page to chart a quick summary of Emscripten support in different browsers. +This page lists some of the most common differences between the latest versions of the major browsers and features that are relevant to Emscripten-compiled applications and games: -- The function emscripten\_get\_now() returns a wallclock time as a float in milliseconds. Opera 12.16 and `on Windows Google Chrome 28.0.1500.95 `_ have a limitation that the timer precision is only in milliseconds. On other major browsers (IE10, Firefox 22, Chrome 28 on non-Windows), emscripten\_get\_now() will have sub-millisecond precision. -- Internet Explorer 10 and older do not support WebGL, which means trying to initialize a GL context via EGL, GLUT, SDL or similar will fail. Emscripten applications that do not depend on OpenGL can still be compiled for this browser however. See `WebGL support in different browsers `__. -- Internet Explorer 11 supports WebGL, but not all of WebGL 1.0, so certain commands, shaders etc. may not work. You may be able to limit your app to using the subset that is supported by IE11. Hopefully IE12 will support everything. -- Opera 12.16 has limited support for the W3C File API, in particular it does not support `createObjectURL functionality `_. As a result, it is not possible to use the browser image codecs on this version of Opera to decode preloaded files in the Emscripten virtual filesystem. +- The function :c:func:`emscripten_get_now` returns a wallclock time as a ``float`` in milliseconds. *Opera 12.16* and on `Windows Google Chrome 28.0.1500.95 `_ have a limitation that the timer precision is only in milliseconds. On other major browsers (*IE10*, *Firefox 22*, *Chrome 28* on non-Windows) it has sub-millisecond precision. +- *Internet Explorer 10* and older do not support WebGL, which means trying to initialize a GL context via EGL, GLUT, SDL or similar will fail. Emscripten applications that do not depend on OpenGL can still be compiled for this browser however. See `WebGL support in different browsers `_. +- *Internet Explorer 11* supports WebGL, but not all of WebGL 1.0, so certain commands, shaders etc. may not work. You may be able to limit your app to using the subset that is supported by IE11. Hopefully IE12 will support everything. +- *Opera 12.16* has limited support for the W3C File API, in particular it does not support `createObjectURL functionality `_. As a result, it is not possible to use the browser image codecs on this version of Opera to decode preloaded files in the Emscripten virtual files system. - OpenAL and SDL audio support in Emscripten depend on the Web Audio API. See `Web Audio API support in different browsers `_. diff --git a/site/source/docs/coding/CodeGuidelinesAndLimitations.rst b/site/source/docs/coding/CodeGuidelinesAndLimitations.rst index eed4a20e6a132..3f3e7df672494 100644 --- a/site/source/docs/coding/CodeGuidelinesAndLimitations.rst +++ b/site/source/docs/coding/CodeGuidelinesAndLimitations.rst @@ -1,49 +1,43 @@ .. _CodeGuidelinesAndLimitations: -============================================= -Code Guidelines And Limitations (wiki-import) -============================================= -.. note:: This article was migrated from the wiki (Fri, 25 Jul 2014 04:21) and is now the "master copy" (the version in the wiki will be deleted). It may not be a perfect rendering of the original but we hope to fix that soon! +========================================================= +Code Guidelines and Limitations (under-construction) +========================================================= -Emscripten can work with pretty much any C/C++ code. However, it might be useful to know what types of code Emscripten compiles better than others, if you are rewriting part of the code you will be compiling. +This article describes the types of code that are more difficult to compile, code which compiles but may run more slowly, and issues and limitations with specific APIs. Developers will find it useful for evaluating the effort to port and re-write code. -Code that CANNOT be compiled +Code that cannot be compiled ============================= -These issues are fundamental difficulties. We can get around them by emulation in theory, but it would be very slow. +The following issues are fundamental difficulties. We can get around them by emulation in theory, but it would be very slow. -- Code that is multithreaded and uses shared state. JS has threads - web workers - but they cannot share state, instead they pass messages. -- Nonportable code that relies on endianness is problematic. It can work with USE_TYPED_ARRAYS=2, but it will not be portable! -- Nonportable code that relies on x86 alignment behavior. X86 allows unaligned reads and writes (so you can read a 16-bit value from a non-even address, i.e., which is only 8-bit aligned address, for example), but other archs do not: ARM will raise SIGILL, and when Emscripten generates JS you will get undefined behavior in this case. (If you build your code with ``SAFE_HEAP=1`` then you will get a clear runtime exception, see :ref:`Debugging`. Note: There is also a code generation mode, UNALIGNED\_MEMORY, which can support unaligned code like this - but it is very slow.) +- Code that is multithreaded and uses shared state. JavaScript has threads - web workers - but they cannot share state, instead they pass messages. +- Nonportable code that relies on endianness is problematic. It can work with :ref:`typed-arrays-mode-2`, but it will not be portable! +- Nonportable code that relies on x86 alignment behavior. X86 allows unaligned reads and writes (so you can read a 16-bit value from a non-even address, i.e., which is only 8-bit aligned address, for example), but other archs do not: ARM will raise ``SIGILL``, and when Emscripten generates JavaScript you will get undefined behavior in this case. (If you build your code with ``SAFE_HEAP=1`` then you will get a clear runtime exception, see :ref:`Debugging`. + + .. note:: The ``UNALIGNED_MEMORY`` code generation mode can support unaligned code like this, but it is very slow. + - Nonportable code that uses low-level features of the native environment, like native stack manipulation (e.g. in conjunction with setjmp/longjmp. We support normal setjmp/longjmp, but not with stack replacing etc.) - Nonportable code that scans registers or the stack, for example to do conservative garbage collection. A variable in a register or on the stack may be held in a JavaScript local variable, which cannot be scanned. (However, you can do conservative scanning when there is no other code on the stack, e.g. from an iteration of the main event loop.) -Function pointer issues ---------------------------------------------------------- - -There are two general issues with function pointers: -1. clang generates different code for C and C++ calls when a structure is passed **by value**. The two formats are incompatible in how we generate code in Emscripten, but each is compatible with itself. You should see a warning during compilation about this, and the workaround is to either not mix C and C++ in that location (just renaming a ``.c`` file to ``.cpp`` for example) or to pass the structure by reference. (More specifically, one convention is ``struct byval`` and the other is ``field a, field b``.) -2. In **asm.js** mode, there is an additional concern, with function tables. Without **asm.js**, all function pointers use a single table, but in **asm.js** each function pointer type has its own table (this allows the JS engine to know the exact type of each function pointer call, and optimize those calls much better than normally). As a consequence though, if you have a function that is say ``int (int)`` (return int, receive int) and you cast it to ``void (int)`` (no return, receive int), then the function pointer call will fail because we are looking in the wrong table. This is undefined behavior in C in any case, so it is recommended to refactor code to avoid this type of situation. You should see compilation warnings about these things. See :ref:`Asm-pointer-casts` for more information. -3. A related issue to do with function pointers is that in ``-O2`` and above we optimize the size of the separate function tables. That means that two functions can have the same function pointer so long as their type is different, and so potentially comparing function pointers of different types can give false positives. Also, it makes bugs with incorrect function pointers potentially more misleading, since there are fewer "holes" in function tables (holes would throw an error instead of running the wrong code). To check if this is causing issues, you can compile with ``-s ALIASING_FUNCTION_POINTERS=0``. - -Code that DOES compile, but might be slower than expected -========================================================== +Code that compiles but might run slowly +======================================= None of the issues here is a showstopper, but they might be slower than you expect. You probably don't need to worry about this stuff, but it might be useful to know about it. - 64-bit ints. Bitwise operations on these are reasonable, but math (+, -, \*, /) is emulated, very slowly. JavaScript does not have native 64-bit ints so this is unavoidable. -- 32-bit multiplication that needs all 64 bits of precision must be emulated like 64-bit integer math (JS doubles work fine up to ~52 bits). By default precise 32-bit multiplication is off as it makes a lot of common 32-bit code very slow, but if you need it you can enable it with ``-s PRECISE_I32_MUL=1``, see **src/settings.js** for more. -- 32-bit floats will end up as 64-bit doubles in JS engines. That means they might be a little slower than expected, depending on your CPU. -- memcpy/memset works, but JS engines don't optimize it very well. Native code will use SIMD on this, JS engines will not - yet. -- Exceptions and longjmp. In JS such code generally makes the JS engine turn off various optimizations. For that reason exceptions are turned off by default in ``-O1`` and above (to re-enable them, run emcc with ``-s DISABLE_EXCEPTION_CATCHING=0``). setjmp also prevents relooping around it. +- 32-bit multiplication that needs all 64 bits of precision must be emulated like 64-bit integer math (JavaScript doubles work fine up to ~52 bits). By default precise 32-bit multiplication is off as it makes a lot of common 32-bit code very slow, but if you need it you can enable it with ``-s PRECISE_I32_MUL=1``, see `src/settings.js `_ for more. +- 32-bit floats will end up as 64-bit doubles in JavaScript engines. That means they might be a little slower than expected, depending on your CPU. +- ``memcpy``/``memset`` works, but JavaScript engines don't optimize it very well. Native code will use SIMD on this, JavaScript engines will not - yet. +- Exceptions and ``longjmp``. In JavaScript such code generally makes the JavaScript engine turn off various optimizations. For that reason exceptions are turned off by default in ``-O1`` and above (to re-enable them, run *emcc* with ``-s DISABLE_EXCEPTION_CATCHING=0``). ``setjmp`` also prevents relooping around it. -Code that MIGHT be useful to avoid -========================================================== +Code that should be avoided when easy to do +=========================================== Avoiding these kinds of code might be nice to do, to prevent warnings and to enable additional optimizations. But unless it is very easy for you to avoid them, just ignore this section. -- Unions. These will trigger ``SAFE_HEAP`` warnings (like *Valgrind*), and make the ``QUANTUM_SIZE=1`` optimization impossible. +- Unions. These will trigger ``SAFE_HEAP`` warnings (like *Valgrind*), and make the ``QUANTUM_SIZE=1`` :ref:`optimization ` impossible. - Bitfields. Also ``SAFE_HEAP`` warnings. - Reusing memory, that is, using the same allocated block of memory once for one kind of object, later for another. This prevents the ``QUANTUM_SIZE=1`` optimization. @@ -53,5 +47,16 @@ Libraries Networking ---------- -- Emscripten supports libc networking functions, but since JS networking is asynchronous, you must limit yourself to asynchronous (nonblocking) operations. +- Emscripten supports libc networking functions, but since JavaScript networking is asynchronous, you must limit yourself to asynchronous (nonblocking) operations. + + +Function pointer issues +======================= + +There are three general issues with function pointers: + +#. clang generates different code for C and C++ calls when a structure is passed **by value**. The two formats are incompatible in how we generate code in Emscripten, but each is compatible with itself. You should see a warning during compilation about this, and the workaround is to either not mix C and C++ in that location (just renaming a **.c** file to **.cpp** for example) or to pass the structure by reference. (More specifically, one convention is ``struct byval`` and the other is ``field a, field b``.) + +#. In **asm.js** mode, there is an additional concern, with function tables. Without **asm.js**, all function pointers use a single table, but in **asm.js** each function pointer type has its own table (this allows the JavaScript engine to know the exact type of each function pointer call, and optimize those calls much better than normally). As a consequence though, if you have a function that is say ``int (int)`` (return int, receive int) and you cast it to ``void (int)`` (no return, receive int), then the function pointer call will fail because we are looking in the wrong table. This is undefined behavior in C in any case, so it is recommended to refactor code to avoid this type of situation. You should see compilation warnings about these things. See :ref:`Asm-pointer-casts` for more information. +#. A related issue to do with function pointers is that in ``-O2`` and above we optimize the size of the separate function tables. That means that two functions can have the same function pointer so long as their type is different, and so potentially comparing function pointers of different types can give false positives. Also, it makes bugs with incorrect function pointers potentially more misleading, since there are fewer "holes" in function tables (holes would throw an error instead of running the wrong code). To check if this is causing issues, you can compile with ``-s ALIASING_FUNCTION_POINTERS=0``. \ No newline at end of file diff --git a/site/source/docs/coding/Garbage_Collection.rst b/site/source/docs/coding/Garbage_Collection.rst index 0e12a76368aec..440cef0893eb1 100644 --- a/site/source/docs/coding/Garbage_Collection.rst +++ b/site/source/docs/coding/Garbage_Collection.rst @@ -1,47 +1,28 @@ .. _GC: -================ -GC (wiki-import) -================ +================================ +Garbage Collection (wiki-import) +================================ .. note:: This article was migrated from the wiki (Fri, 25 Jul 2014 04:21) and is now the "master copy" (the version in the wiki will be deleted). It may not be a perfect rendering of the original but we hope to fix that soon! -Emscripten has support for a Boehm-like API for garbage collection in -C/C++ programs. This is useful if your application uses the Boehm API or -if you are compiling a language like Java into C/C++ with the goal of -then translating it to JavaScript. +Emscripten has support for a Boehm-like API for garbage collection in C/C++ programs. This is useful if your application uses the Boehm API or if you are compiling a language like Java into C/C++ with the goal of then translating it to JavaScript. API Changes From Boehm ---------------------- -There is no way to run another thread that interrupts the program at -intervals in order to GC. So you need to call ``GC_MAYBE_COLLECT`` at -reasonable intervals, which will do a collection if enough allocations -happened since the last one. If you compile to HTML, a timer will be -spun for this automatically and you don't need to do anything. +There is no way to run another thread that interrupts the program at intervals in order to GC. So you need to call ``GC_MAYBE_COLLECT`` at reasonable intervals, which will do a collection if enough allocations happened since the last one. If you compile to HTML, a timer will be spun for this automatically and you don't need to do anything. -You can also call ``GC_FORCE_COLLECT`` which forces a collection. This -is useful if there are times in your app when responsiveness is not -important (for example, right before starting a new level in a game). +You can also call ``GC_FORCE_COLLECT`` which forces a collection. This is useful if there are times in your app when responsiveness is not important (for example, right before starting a new level in a game). Mechanism --------- -Static allocations are scanned, but the C and JS stacks are not. We can -add such scanning at the cost of runtime performance, however, you don't -need stack scanning if you compile for browsers and call -``GC_MAYBE_COLLECT`` from a ``setInterval``, since the interval will run -when there is no relevant C or JS stack to scan (as mentioned before, -such a timer will be run for you automatically if you are compiling to -HTML). +Static allocations are scanned, but the C and JS stacks are not. We can add such scanning at the cost of runtime performance, however, you don't need stack scanning if you compile for browsers and call ``GC_MAYBE_COLLECT`` from a ``setInterval``, since the interval will run when there is no relevant C or JS stack to scan (as mentioned before, such a timer will be run for you automatically if you are compiling to HTML). Pitfalls -------- -The main risk with the current implementation is that we do not force a -collection directly from allocations. So if you allocate a lot in -between collections, you can run out of memory. You can call -``GC_FORCE_COLLECT`` to prevent this in some cases if you know relevant -parts in your code. +The main risk with the current implementation is that we do not force a collection directly from allocations. So if you allocate a lot in between collections, you can run out of memory. You can call ``GC_FORCE_COLLECT`` to prevent this in some cases if you know relevant parts in your code. Relevant Files -------------- diff --git a/site/source/docs/compiling/Code-Generation-Modes.rst b/site/source/docs/compiling/Code-Generation-Modes.rst index aff3b841c082c..bf695341c0a36 100644 --- a/site/source/docs/compiling/Code-Generation-Modes.rst +++ b/site/source/docs/compiling/Code-Generation-Modes.rst @@ -72,18 +72,26 @@ Exceptions can work in code compiled by emscripten, however due to how JS engine To get full exception handling support in ``-O1`` and above, run emcc with ``-s DISABLE_EXCEPTION_CATCHING=0``. Note that enabling exceptions will make the code larger due to the additional try-catch blocks (which cannot be minified very well). -Memory Compression (a.k.a QUANTUM\_SIZE == 1) +.. _code-generation-modes-quantum-size: + +Memory Compression (a.k.a QUANTUM_SIZE == 1) --------------------------------------------- -By default, Emscripten sets QUANTUM\_SIZE to 4, which means that a 'normal' element - like an int or a pointer - takes 4 'bytes'. That is the normal behavior on 32-bit systems, and allows Emscripten to properly compile a great deal of C/C++ code. However, the downside is that each int or pointer takes 4 places in the HEAP array, which is how Emscripten models the normal C/C++ memory space. This makes HEAP much bigger than it needs to be, which takes more memory, and also slows things down (for example, memset ends up clearing larger areas of memory). +By default, Emscripten sets ``QUANTUM_SIZE`` to 4, which means that a 'normal' element - like an int or a pointer - takes 4 'bytes'. That is the normal behavior on 32-bit systems, and allows Emscripten to properly compile a great deal of C/C++ code. However, the downside is that each int or pointer takes 4 places in the HEAP array, which is how Emscripten models the normal C/C++ memory space. This makes HEAP much bigger than it needs to be, which takes more memory, and also slows things down (for example, memset ends up clearing larger areas of memory). -By setting QUANTUM\_SIZE to 1, memory is 'compressed' - it is not longer isomorphic to normal C/C++ memory. So for example a structure with an int, a double, and a pointer would have a size of 3 (one for each variable), instead of the normal 16 (4 for the int and pointer, 8 for the double). This leads to significantly more optimized code, both in terms of speed and memory use. +By setting QUANTUM_SIZE to 1, memory is 'compressed' - it is not longer isomorphic to normal C/C++ memory. So for example a structure with an int, a double, and a pointer would have a size of 3 (one for each variable), instead of the normal 16 (4 for the int and pointer, 8 for the double). This leads to significantly more optimized code, both in terms of speed and memory use. -However, this is risky, since with QUANTUM\_SIZE of 1, Emscripten rewrites the .ll, trying to fix all the hardcoded places where it assumes the normal memory space. So consider this experimental for now. +However, this is risky, since with QUANTUM\_SIZE of 1, Emscripten rewrites the .ll, trying to fix all the hard-coded places where it assumes the normal memory space. So consider this experimental for now. Notes: -- With QUANTUM\_SIZE == 1, Emscripten will warn you about ptrtoint and inttoptr operations (in the generated .js file). You should make sure there are no problems in each of those cases, and perhaps modify the original C/C++ to avoid generating that kind of code (the changes are often simple). -- You can **not** use QUANTUM\_SIZE == 1 with typed arrays mode 2. The reason is that typed arrays mode 2 is C-like memory layout, whereas in QUANTUM\_SIZE == 1 we radically change the layout (ints take 1 memory address instead of 4, etc.), and the two can't be mixed. +- With QUANTUM_SIZE == 1, Emscripten will warn you about ``ptrtoint`` and ``inttoptr`` operations (in the generated .js file). You should make sure there are no problems in each of those cases, and perhaps modify the original C/C++ to avoid generating that kind of code (the changes are often simple). +- You can **not** use ``QUANTUM_SIZE == 1`` with typed arrays mode 2. The reason is that typed arrays mode 2 is C-like memory layout, whereas in ``QUANTUM_SIZE == 1`` we radically change the layout (ints take 1 memory address instead of 4, etc.), and the two can't be mixed. + +The second version of the Bullet demo in Emscripten uses ``QUANTUM_SIZE == 1``. It appears to give a speedup of around 25%. + + + +.. todo:: **HamishW** In :ref:`CodeGuidelinesAndLimitations` it mentions a code generation mode UNALIGNED_MEMORY - perhaps add? -The second version of the Bullet demo in Emscripten uses QUANTUM\_SIZE == 1. It appears to give a speedup of around 25%. +.. todo:: **HamishW** SAFE_HEAP gets mentioned. Anything we can link to? diff --git a/site/source/docs/getting_started/FAQ.rst b/site/source/docs/getting_started/FAQ.rst index 2a733cc079db2..1bc5de923558a 100644 --- a/site/source/docs/getting_started/FAQ.rst +++ b/site/source/docs/getting_started/FAQ.rst @@ -14,7 +14,7 @@ See the :ref:`Tutorial` and :ref:`emccdoc`. I get many errors building basic code and the tests? ==================================================== -All the tests in the :ref:`Emscripten test suite ` are known to build and pass on the **master** branch, so it is likely that there is some problem with your environment. +All the tests in the :ref:`Emscripten test suite ` are known to build and pass on the **master** branch, so if these are failing it is likely that there is some problem with your environment. First call ``./emcc -v``, which runs basic sanity checks and prints out useful environment information. If that doesn't help, follow the instructions in :ref:`verifying-the-emscripten-environment`. @@ -24,9 +24,9 @@ You might also want to go through the :ref:`Tutorial` again, as this is updated I tried something and it doesn't work? ====================================== -This site has comprehensive documentation. If you tried "something" and it fails (for example a :ref:`compiler flag `, or a *libc* function), one of the first options should therefore be to search the site. +If something doesn't work (for example a :ref:`compiler flag `, a *libc* function, etc.) then first search the comprehensive documentation on this site. -Another really good option is to see if there is a test for the failing functionality in the :ref:`Emscripten test suite ` (run ``grep -r`` in ``tests/``). **All** the tests are known to pass on the master branch, so they provide concrete "known-good" examples of how various options and code are used. +Next check if there is a test for the failing functionality in the :ref:`Emscripten test suite ` (run ``grep -r`` in **tests/**). **All** the tests are known to pass on the master branch, so they provide concrete "known-good" examples of how various options and code are used. Do I need to change my build system to use Emscripten? @@ -35,96 +35,124 @@ Do I need to change my build system to use Emscripten? In most cases you will be able to use your project's current build system with Emscripten. See :ref:`Building-Projects`. -My code cannot access a file in the same directory? -=================================================== -Emscripten-generated code cannot by default access local files on your machine like a native application. See :ref:`Filesystem-Guide` for details: you can in node allow such access, and in other platforms you can use preloading to work around lack of synchronous file IO. +Code compilation is slow? +========================= +Emscripten makes some trade-offs that make the generated code faster and smaller, at the cost of longer compilation times. For example, we build parts of the standard library along with your code which enables some additional optimizations, but takes a little longer to compile. -My code compiles slowly. -======================== +.. note:: You can determine what compilation steps take longest by compiling with ``EMCC_DEBUG=1`` in the environment and then reviewing the debug logs (by default in ``/tmp/emscripten_temp``). Note that compiling in debug mode takes longer than normal, because we print out a lot of intermediate steps to disk. -Emscripten makes some tradeoffs that make the generated code faster and smaller, at the cost of longer compilation times. For example, we build parts of the standard library along with your code which enables some additional optimizations, but takes a little longer to compile. +The main tips for improving build time are: -Emscripten can run some passes in parallel (specifically, the JS opts), and will do so automatically, so running on a machine with more cores can give you almost a linear speedup (so doubling the amount of cores can almost halve the amount of time it takes to build and so forth). To see details of how work is parallelized, compile with ``EMCC_DEBUG=1`` in the environment (note though that in that debug mode compilation takes longer than normal, because we print out a lot of intermediate steps to disk, by default to ``/tmp/emscripten_temp``, but it's still useful to see which stages are slowing you down). You can affect how many cores are using with ``EMCC_CORES=N``, which can be useful if you have many cores but relatively less memory. +- Create fully optimized builds less frequently — use ``-O0`` during frequent development iterations (or don't specify an optimization level). + + - Compiling with higher levels of optimization can in some cases be noticeably slower: ``-O2`` is slower than ``-O1``, which is in turn slower than ``-O0``. + - Compiling with ``-O3`` is **especially** slow — this can be mitigated by also enabling ``-s AGGRESSIVE_VARIABLE_ELIMINATION=1`` (removing variables makes the ``-O3`` regalloc easier). + +- Compile without :ref:`line number debug information ` (use ``-O1`` or ``-g0`` instead of ``-g``): -Note that optimization can in some cases be noticeably slower than unoptimized code, ``-O1`` is slower than ``-O0``, which in turn is slower than ``-O2`` (in return, though, they greatly improve the speed of the generated code). It might be useful to use ``-O0`` (or not specify an optimization level) during quick development iterations and to do fully optimized builds less frequently. Note that ``-O3`` is **especially** slow (you can mitigate the ``-O3`` slowness by also enabling ``-s AGGRESSIVE_VARIABLE_ELIMINATION=1``, as it removes variables which makes the ``-O3`` regalloc easier). + - Currently builds with line-number debug information are slow (see issue `#216 `_). Stripping the debug information significantly improves compile times. + +- Compile on a machine with more cores: -Currently builds with line-number debug info (where the source code was compiled with ``-g``) are slow, see issue #216. Stripping the debug info leads to much faster compile times. + - Emscripten can run some passes in parallel (specifically, the JavaScript optimisations). Increasing the number of cores results in an almost linear improvement. + - Emscripten will automatically use more cores if they are available. You can control how many cores are used with ``EMCC_CORES=N`` (this is useful useful if you have many cores but relatively less memory). -My code runs slowly. + +My code runs slowly? ===================== -Make sure you build with ``-O2`` so code is optimized. **This is necessary both for each source file, and for the final stage of linking and compiling to JS**, see more details :ref:`Building-Projects`. See :ref:`Optimizing-Code` for more info. +Make sure you optimize code by building with ``-O2`` (even more :ref:`aggressive optimization ` is available, at the cost of significantly increased compilation time). +.. note: This is necessary both for each source file, and for the final stage of linking and compiling to JavaScript. For more information see :ref:`Building-Projects` and :ref:`Optimizing-Code`. -My code is large. -=========================== -Make sure you build with ``-O2`` so code is optimized, which includes minification to reduce size. You should also set up gzip compression on your webserver, which all browsers now support. +My code is large? +================= -You can use closure compile to reduce code size even more with ``--closure 1``, however that will require that your code with with closure compiler advanced optimizations, including proper exports and so forth. It is usually not worth the effort over an optimized build+server gzip. +Make sure you build with ``-O2`` so code is optimized and minified. You should also set up gzip compression on your webserver, which all browsers now support. +.. note:: You can :ref:`use the closure compiler ` to reduce code size even further (``--closure 1``). However that will require that your code be prepared for closure compiler advanced optimizations, including proper exports and so forth. It is usually not worth the effort over an optimized build and supporting gzip on your webserver. -When I compile code that should work, I get odd errors in Emscripten about various things. I get different errors (or it works) on another machine. -========================================================================================================================================================================== -Make sure you are using the Emscripten bundled system headers. Using ``emcc`` will do so by default, but if you compile into LLVM bitcode yourself, or you use your local system headers even with ``emcc``, problems can happen. +Compiling code that works on another machine gives me errors? +============================================================= -My large codebase runs ok, but the time it takes to start up is significant. What can I do to improve that? -======================================================================================================================================== +Make sure you are using the Emscripten bundled system headers. Using :ref:`emcc ` will do so by default, but problems may occur if you use your local system headers with ``emcc`` or compile into LLVM bitcode yourself. -First, make sure you are running an optimized build (which will be much smaller and faster to start up). Then, if the sheer code size is causing the slow startup, you can try the `outlining option in emscripten `__. -Another possible factor is network latency. If you load data off the network and also have a big codebase, try to put the file loading code in a separate script element - that is, run the file packager (``tools/file_packager.py``) and put its code in one script element, and in another script element after it put the generated codebase. That will allow the browser to start the network download immediately, so it can run in parallel to the browser parsing and starting up the codebase. +My large codebase runs well, but startup time is significant? +============================================================= +Make sure that you are running an :ref:`optimized build ` (smaller builds are faster to start up). If the sheer code size is causing the slow startup, you can try `Outlining: a workaround for JITs and big functions `_. -My code fails to compile, the error includes something about inline assembly (or ``{"text":"asm"}``). -======================================================================================================================================== +Network latency is also a possible factor in startup time. Consider putting the file loading code in a separate script element from the generated code so that the browser can start the network download in parallel to starting up the codebase (run the :ref:`file packager ` and put file loading code in one script element, and the generated codebase in a following script element). -Emscripten cannot compile inline assembly code, which is CPU specific, because Emscripten is not a CPU emulator. -Many projects have build options that generate only platform-independent code, without inline assembly. That should be used for Emscripten. For example, the following might help (and are done automatically for you by ``emcc``): +My code fails to compile with an error message about inline assembly (or ``{"text":"asm"}``)? +============================================================================================= - :: +Emscripten cannot compile inline assembly code (because it is CPU specific, and Emscripten is not a CPU emulator). - #undef __i386__ - #undef __x86_64__ +You will need to find where inline assembly is used, and disable it or replace it with platform-independent code. -Since when no CPU-specific ``#define`` exists, many projects will not generate CPU specific code. In general though, you will need to find where inline assembly is generated, and how to disable that. +.. note:: Emscripten automatically unsets the following ``#define`` values, as these are commonly set in projects to enable platform dependent code (inline assembly): + :: -How do I run an event loop? -=========================== + #undef __i386__ + #undef __x86_64__ -To run a C function repeatedly, use :c:func:`emscripten_set_main_loop` (**emscripten.h**). The other functions in that file are also useful, they let you do things like add events that block the main loop, etc. -To respond to browser events and so forth, use the SDL API normally. See the SDL tests for examples (look for SDL in ``tests/runner.py``). +.. _faq-my-html-app-hangs: -See also the next question. +My HTML app hangs? +================== +The browser event model uses *co-operative multitasking* — each event has a "turn" to run, and must then return control to the browser event loop so that other events can be processed. A common cause of HTML pages hanging is JavaScript that does not complete and return control to the browser. -My HTML app hangs. -================== +Graphical C++ apps typically have an "infinite" main loop in which event handling, processing and rendering is done, followed by a delay to keep the frame-rate right (``SDL_DELAY`` in SDL apps). As the main loop does not complete it cannot return control to the browser, and the app will hang. + +Apps that use an infinite loop should be re-coded to put the actions for a single iteration of the main loop are put into a single "finite" function. In the native build this function can be run in an infinite loop as before. In the Emscripten build it is set as the :ref:`main loop function ` and will be called by the browser at a specified frequency. + +There is more information on this topic in :ref:`Emscripten-Browser-Environment`. + + +.. _faq-how-run-event-loop: + +How do I run an event loop? +=========================== - **A.** Graphical C++ apps typically have a main loop that is an infinite loop, in which event handling is done, processing and rendering, then SDL_Delay. However, in JS there is no way for SDL_Delay to actually return control to the browser event loop. To do that, you must exit the current code. See - :ref:`Emscripten-Browser-Environment`. +To run a C function repeatedly, use :c:func:`emscripten_set_main_loop` (this is discussed in :ref:`Emscripten-browser-environment`). The related functions in :ref:`emscripten.h ` are also useful, allowing you to add events that block the main loop, etc. -My SDL app doesn't work. +To respond to browser events use the SDL API in the normal way. There are examples in the SDL tests (search for SDL in **tests/runner.py**). + +See also: :ref:`faq-my-html-app-hangs` + + + +My SDL app doesn't work? ======================== See the SDL automatic tests for working examples: ``python tests/runner.py browser``. + How do I link against system libraries like SDL, boost, etc.? -================================================================== +============================================================= -System libraries that are included with Emscripten - libc, libc++ (C++ standard library) and SDL - are automatically included when you compile (and just the necessary parts of them). You don't even need ``-lSDL``, unlike other compilers (but ``-lSDL`` won't hurt either). +System libraries that are included with Emscripten are automatically linked when you compile (just the necessary parts). This includes *libc*, *libc++* (C++ standard library) and SDL. -Other libraries not included with Emscripten, like boost, you would need to compile yourself and link with your program, just as if they were a module in your project. For example, see how `BananaBread links in libz `_. (Note that in the specific case of boost, if you only need the boost headers, you don't need to compile anything.) +Libraries which are not included with Emscripten (like Boost) must be compiled and linked with the program just as if they were a module in the project. For example, see how `BananaBread links in libz `_. -Another option for libraries not included is to implement them as a JS library, like emscripten does for libc (minus malloc) and SDL (but not libc++ or malloc). See ``--js-library`` in emcc. +Another option is to implement needed as a JavaScript library (see ``--js-library`` in :ref:`emcc `). Emscripten itself does this for *libc* (not including *malloc*) and SDL (but not *libc++* or *malloc*). + +.. note:: + + - Unlike other compilers, you don't need ``-lSDL`` to include SDL (specifying it will do no harm). + - In the specific case of *Boost*, if you only need the boost headers, you don't need to compile anything. How can my compiled program access files? @@ -133,35 +161,78 @@ How can my compiled program access files? Emscripten uses a virtual file system that may be preloaded with data or linked to URLs for lazy loading. See the :ref:`Filesystem-Guide` for more details. -Functions in my C/C++ source code vanish when I compile to JavaScript, and/or I get ``No functions to process``..? +My code cannot access a file in the same directory? +=================================================== + +Emscripten-generated code running *in the browser* cannot access files in the local file system. Instead you can use :ref:`preloading ` and :ref:`embedding ` to work around lack of synchronous file IO. See :ref:`Filesystem-Guide` for more information. + +It is possible to allow access to local file system for code running in *node.js*. + + +.. _faq-when-safe-to-call-compiled-functions: + +How can I tell when the page is fully loaded and it is safe to call compiled functions? +======================================================================================= + +Calling a compiled function before a page has fully loaded can result in an error, if the function relies on files that may not be present (for example the :ref:`.mem ` file and :ref:`preloaded ` files are loaded asynchronously). + +The easiest way to find out when loading is complete is to add a ``main()`` function, and within it call a JavaScript function to notify your code that loading is complete. + +.. note:: The ``main()`` function is called after startup is complete as a signal that it is safe to call any compiled method. + +For example if ``allReady()`` is a JavaScript function you want called when everything is ready, you can do: + +:: + + #include + + int main() { + EM_ASM( allReady() ); + } + + + +Functions in my C/C++ source code vanish when I compile to JavaScript, and/or I get ``No functions to process..``? ================================================================================================================== - **A.** By default Emscripten does dead code elimination to minimize code size. However, it might end up removing functions you want to call yourself, that are not called from the compiled code (so the LLVM optimizer thinks they are unneeded). You can run emcc with ``-s LINKABLE=1`` which will disable link-time optimizations and dead code elimination, but this makes the code larger and less optimized than it could be. Instead, you should prevent specific functions from being eliminated by adding them to EXPORTED_FUNCTIONS (see ``src/settings.js``), for example, run emcc with something like ``-s EXPORTED_FUNCTIONS="['_main', '_my_func']"`` in order to keep my_func from being removed/renamed (as well as ``main()``)). Note that this assumes my_func is a C function, otherwise you would need to write out the C++ name mangling. +By default, Emscripten does dead code elimination of functions that are not called from the compiled code. While this does minimize code size, it can remove functions that you plan to call yourself (outside of the compiled code). - It can be useful to compile with ``EMCC_DEBUG=1`` (``EMCC_DEBUG=1 emcc ..``). Then the compilation steps are split up and saved in ``/tmp/emscripten_temp``. You can then see at what stage the code vanishes (you will need to do ``llvm-dis`` on the bitcode stages to read them, or ``llvm-nm``, etc.). +To make sure a function is accessible to be called from normal JavaScript it must be added to the `EXPORTED_FUNCTIONS `_ using the *emcc* command line. For example, to prevent functions ``my_func()`` and ``main()`` from being removed/renamed, run *emcc* with: ``-s EXPORTED_FUNCTIONS="['_main', '_my_func']"``. - In summary, the general procedure for making sure a function is accessible to be called from normal JS later is (1) make a C function interface (to avoid C++ name mangling), (2) run emcc with ``-s EXPORTED_FUNCTIONS="['_main', '_yourCfunc']"`` to make sure it is kept alive during optimization. +.. note:: - If your function is used in other functions, LLVM may inline it and it will not show up. In this case you can define it with ``void EMSCRIPTEN_KEEPALIVE yourCfunc() {..}`` which will preserve it (see :c:type:`EMSCRIPTEN_KEEPALIVE`). + - Exported functions need to be C functions (to avoid C++ name mangling). + - Running *emcc* with ``-s LINKABLE=1`` will also disable link-time optimizations and dead code elimination. This is not recommended as it makes the code larger and less optimized. - Another possible issue here is linking of ``.a`` files. ``.a`` files link only the internal object files needed by previous files on the command line, so the order of files matters, and this can be surprising. If you are linking ``.a`` files, make sure they are at the end of the list of files, and in the right order amongst themselves, or just use ``.so`` files instead in your project. +If your function is used in other functions, LLVM may inline it and it will not show up. Prevent inlining by defining the function with :c:type:`EMSCRIPTEN_KEEPALIVE`: :: - Note: In LLVM 3.2 dead code elimination is significantly more aggressive. All functions not kept alive through EXPORTED_FUNCTIONS will be potentially eliminated. Make sure to keep the things you need alive using one or both of those methods. + void EMSCRIPTEN_KEEPALIVE yourCfunc() {..} -The FS API is not available when I build with closure? -======================================================= +Another possible issue here is linking of ``.a`` files. ``.a`` files link only the internal object files needed by previous files on the command line, so the order of files matters, and this can be surprising. If you are linking ``.a`` files, make sure they are at the end of the list of files, and in the right order amongst themselves, or just use ``.so`` files instead in your project. -Closure compiler will minify the FS API code. To write code that uses it, it must be optimized **with** the FS API code by closure. To do that, use emcc's ``--pre-js`` option, see ``emcc --help``. +Note: In LLVM 3.2 dead code elimination is significantly more aggressive. All functions not kept alive through EXPORTED_FUNCTIONS will be potentially eliminated. Make sure to keep the things you need alive using one or both of those methods. +.. tip:: It can be useful to compile with ``EMCC_DEBUG=1`` set for the environment (``EMCC_DEBUG=1 emcc ..`` on Linux, ``set EMMCC_DEBUG=1`` on Windows) which splits up the compilation steps and saves them in ``/tmp/emscripten_temp``. You can then see at what stage the code vanishes (you will need to do ``llvm-dis`` on the bitcode stages to read them, or ``llvm-nm``, etc.). -My code breaks with ``-O2 --closure 1``, giving odd errors..? -==================================================================== +**HamishW** When use KEEPALIVE, when use EXPORTED FUNCTIONS. Note about LLVM3.2 being more aggressive a bit confusing in context. -The likely problem is that Closure Compiler minifies variable names. Names like ``i,j,xa`` can be generated, and if other code has such variables in the global scope, bad things can happen. - -To check if this is the problem, compile with ``-O2`` (without ``--closure 1``). If that works, name minification might be the problem. If so, wrapping the generated code in a closure should fix it. (Or, wrap your other code in a closure, or stop it from using small variable names in the global scope, you might be using such variables by mistake by forgetting a ``var`` and assigning to a variable - which makes it be in the global scope.) - -To 'wrap' code in a closure, do something like this: + +The File System API is not available when I build with closure? +=============================================================== + +The :term:`Closure Compiler` will minify the File Server API code. Code that uses the file system must be optimized **with** the File System API, using emcc's ``--pre-js`` :ref:`option `. + + +My code breaks and gives odd errors when using ``-O2 --closure 1``? +=================================================================== + +The :term:`Closure Compiler` minifies variable names, which results in very short variable names like ``i``, ``j``, ``xa``. If other code declares variables with the same names in global scope, this can cause serious problems. + +This is likely to be the cause if you can successfully compile with ``-O2`` set but **not** ``--closure 1``. + +One solution is to stop using small variable names in the global scope (often this is a mistake - forgetting to use ``var`` when assigning to a variable). + +Another alternative is to wrap the generated code (or your other code) in a closure, as shown: :: @@ -170,58 +241,56 @@ To 'wrap' code in a closure, do something like this: return Module; })(); -I get ``undefined is not a function`` or ``NAME is not a function``..? -===================================================================================== -The likely cause is an undefined function - something that was referred to, but not implemented or linked in. If you get ``undefined``, look at the line number to see the function name. +I get ``undefined is not a function`` or ``NAME is not a function``? +==================================================================== -Emscripten by default does *not* give fatal errors on undefined symbols, so you can get runtime errors like these (because in practice in many codebases it is easiest to get them working without refactoring them to remove all undefined symbol calls). If you prefer compile-time notifications, run emcc with ``-s WARN_ON_UNDEFINED_SYMBOLS=1`` or ``-s ERROR_ON_UNDEFINED_SYMBOLS=1``. +The likely cause is an undefined function — a function that was referred to, but not implemented or linked in. If you get ``undefined``, look at the line number to see the function name. -Aside from just forgetting to link in a necessary object file, one possible cause for this error is inline functions in headers. If you have a header with ``inline int my_func() { .. }`` then clang may not actually inline the function (since inline is just a hint), and also not generate code for it (since it's in a header), so the generated bitcode and js will not have that function implemented. One solution is to add ``static``, that is ``static inline int my_func() { .. }`` which forces code to be generated in the object file. +Emscripten by default does *not* give fatal errors on undefined symbols, so you can get *runtime* errors like these (because in practice for many codebases it is easiest to get them working without refactoring them to remove all undefined symbol calls). If you prefer compile-time notifications, run *emcc* with ``-s WARN_ON_UNDEFINED_SYMBOLS=1`` or ``-s ERROR_ON_UNDEFINED_SYMBOLS=1``. -I get an odd python error complaining about libcxx.bc or libcxxabi.bc..? -===================================================================================== +Aside from just forgetting to link in a necessary object file, one possible cause for this error is inline functions in headers. If you have a header with ``inline int my_func() { .. }`` then *Clang* may not actually inline the function (since inline is just a hint), and also not generate code for it (since it's in a header). The result is that the generated bitcode and JavaScript will not have that function implemented. One solution is to add ``static`` to the function declaration, which forces code to be generated in the object file: ``static inline int my_func() { .. }``. -Possibly building libcxx or libcxxabi failed. Go to system/lib/libcxx (or libcxxabi) and do ``emmake make`` to see the actual error. Or, clean the emscripten cache (``~/.emscripten_cache``) and then compile your file with ``EMCC_DEBUG=1`` in the environment. libcxx will then be built in - ``/tmp/emscripten_temp/libcxx``, and you can see ``configure*,make*`` files that are the output of configure and make, etc. +I get an odd python error complaining about libcxx.bc or libcxxabi.bc? +====================================================================== -One possible cause of this error is the lack of ``make``, which is necessary to build these libraries. If you are on Windows, you need cygwin which supplies ``make``. +A possible cause it that building *libcxx* or *libcxxabi* failed. Go to **system/lib/libcxx** (or libcxxabi) and do ``emmake make`` to see the actual error. Or, clean the Emscripten cache (``./emcc --clear-cache``) and then compile your file with ``EMCC_DEBUG=1`` in the environment. *libcxx* will then be built in **/tmp/emscripten_temp/libcxx**`, and you can see ``configure*, make*`` files that are the output of configure and make, etc. -Running LLVM bitcode generated by emcc through ``lli`` breaks with errors about ``impure_ptr`` stuff..? -======================================================================================================== +Another possible cause of this error is the lack of ``make``, which is necessary to build these libraries. If you are on Windows, you need *cmake*. -First of all, lli is not maintained (sadly) and has odd errors and crashes. However there is ``tools/nativize_llvm.py`` which compiles bitcode to a native executable. It will also hit the ``impure_ptr`` error though. -The issue is that newlib uses that impure pointer stuff, while glibc uses something else. So bitcode build with the emscripten SDK (which emcc does) will not run locally, unless your machine uses newlib (which basically only embedded systems do). The impure_ptr stuff is limited, however, it only applies to explicit use of ``stdout`` etc. So ``printf(..)`` will work, but ``fprintf(stdout, ..)`` will not. So often it is simple to modify your code to not hit this problem. +Running LLVM bitcode generated by emcc through **lli** breaks with errors about ``impure_ptr``? +=============================================================================================== -I get a stack size error when optimizing (``RangeError: Maximum call stack size exceeded`` or similar)? -======================================================================================================================================= +.. note:: `lli `_ is not maintained, and has odd errors and crashes. We do include **tools/nativize_llvm.py** (which compiles bitcode to a native executable) but it will also hit the ``impure_ptr`` error. -You may need to increase the stack size for node. On linux and mac, you can just do ``NODE_JS = ['node', '--stack_size=8192']`` or such (in ``~/.emscripten``). On windows, you will also need ``--max-stack-size=8192``, and also to run ``editbin /stack:33554432 node.exe``. +The issue is that *newlib* uses ``impure_ptr`` code, while *glibc* uses something else. The result is that bitcode built with the Emscripten will not run locally unless your machine uses *newlib* (basically, only embedded systems). +The ``impure_ptr`` error only occurs during explicit use of ``stdout`` etc., so ``printf(..)`` will work, but ``fprintf(stdout, ..)`` will not. **Usually it is simple to modify your code to avoid this problem.** -I get ``error: cannot compile this aggregate va_arg expression yet`` and it says ``compiler frontend failed to generate LLVM bitcode, halting`` afterwards. -============================================================================================================================================================================================= -This is a limitation of the le32 frontend in clang. You can use the x86 frontend instead by compiling with ``EMCC_LLVM_TARGET=i386-pc-linux-gnu`` in the environment (however you will lose the advantages of le32 which includes better alignment of doubles). +I get a stack size error when optimizing: ``RangeError: Maximum call stack size exceeded`` or similar? +====================================================================================================== -.. _faq-when-safe-to-call-compiled-functions: +You may need to increase the stack size for :term:`node.js`. + +On Linux and Mac OS X, you can just do ``NODE_JS = ['node', '--stack_size=8192']`` in the :ref:`compiler-configuration-file`. On Windows, you will also need ``--max-stack-size=8192``, and also to run ``editbin /stack:33554432 node.exe``. -I am building a library, and sometimes I get an error when I call a compiled function before the page fully loaded. How can I tell when is safe to call it? -============================================================================================================================================================================ -The easiest way to find out when loading is complete (which is asynchronous, as it often requires loading files, such as the .mem file or preloade files), is to just add a ``main()`` function. It will be called when it is safe to do so, after startup is complete, so that is a signal that it is safe to call any compiled method. +I get ``error: cannot compile this aggregate va_arg expression yet`` and it says ``compiler frontend failed to generate LLVM bitcode, halting`` afterwards. +============================================================================================================================================================================================= -You can make ``main()`` call your JS to notify it, for example if ``allReady()`` is a JS function you want called when everything is ready, you can do +This is a limitation of the le32 frontend in :term:`Clang`. You can use the x86 frontend instead by compiling with ``EMCC_LLVM_TARGET=i386-pc-linux-gnu`` in the environment (however you will lose the advantages of le32 which includes better alignment of doubles). -:: + +Build from source fails during linking (at 100%) +================================================ - #include +Building :ref:`Fastcomp from source ` (and hence the SDK) can fail at 100% progress. This is due to out of memory in the linking stage, and is reported as error: ``collect2: error: ld terminated with signal 9 [Killed]``. + +The solution is to ensure the system has sufficient memory. On Ubuntu 14.04,1 LTS 64bit use at least 6Gb. - int main() { - EM_ASM( allReady() ); - } The name of the project sounds weird to me diff --git a/site/source/docs/getting_started/Tutorial.rst b/site/source/docs/getting_started/Tutorial.rst index 7098331b8a77d..0c6989ad8f9a6 100644 --- a/site/source/docs/getting_started/Tutorial.rst +++ b/site/source/docs/getting_started/Tutorial.rst @@ -6,7 +6,7 @@ Emscripten Tutorial (ready-for-review) **Using Emscripten is, at a base level, fairly simple. This tutorial takes you through the steps needed to compile your first Emscripten examples from the command line. It also shows how to work with files and set the main compiler optimization flags.** -.. tip:: Check out :ref:`this topic ` if you want to use *Emscripten* with Microsoft *Visual Studio 2010*. +.. tip:: Check out :ref:`this topic ` if you want to use *Emscripten* with Microsoft *Visual Studio 2010*. First things first ====================== @@ -57,7 +57,7 @@ There should now be an **a.out.js** file in the current directory. Run it using :: - ./node a.out.js + node a.out.js This prints "hello, world!" to the console, as expected. diff --git a/site/source/docs/getting_started/downloads.rst b/site/source/docs/getting_started/downloads.rst index 27085239dd816..d541e11918866 100644 --- a/site/source/docs/getting_started/downloads.rst +++ b/site/source/docs/getting_started/downloads.rst @@ -6,7 +6,7 @@ Download and install (ready-for-review) **The Emscripten SDK provides the whole Emscripten toolchain (Clang, Python, Node.js and Visual Studio integration) in a single easy-to-install package, with integrated support for** :ref:`updating to newer SDKs ` **as they are released.** -.. tip:: If you are :ref:`contributing ` to Emscripten you should first install the SDK, and then use it to :ref:`build Emscripten from source `. +.. tip:: If you are :ref:`contributing ` to Emscripten you should :ref:`build Emscripten from source `. SDK Downloads diff --git a/site/source/docs/getting_started/index.rst b/site/source/docs/getting_started/index.rst index 6b579725afc7c..22d10056db7ac 100644 --- a/site/source/docs/getting_started/index.rst +++ b/site/source/docs/getting_started/index.rst @@ -8,7 +8,7 @@ Now you know why Emscripten is :ref:`right for you `, it's tim This section provides a walk-through of :ref:`downloading and installing the SDK ` and the basics of :ref:`using the Emscripten toolchain `. The general :ref:`FAQ` answers many common questions about setting up and using Emscripten. -We also explain where to :ref:`Report Bugs ` in the toolchain and the site, and how to use Emscripten with :ref:`Visual Studio 2010 ` (Windows only). +We also explain where to :ref:`Report Bugs ` in the toolchain and the site, and how to use Emscripten with :ref:`Visual Studio 2010 ` (Windows only). .. toctree:: :maxdepth: 1 diff --git a/site/source/docs/packaging/Filesystem-Guide.rst b/site/source/docs/packaging/Filesystem-Guide.rst index f9e2166391539..cf62cb7d722d1 100644 --- a/site/source/docs/packaging/Filesystem-Guide.rst +++ b/site/source/docs/packaging/Filesystem-Guide.rst @@ -19,6 +19,8 @@ For concrete examples of using the filesystem API, see the automatic tests in `` The reason for the filesystem API is that JavaScript is most often run in web browsers, which sandbox content and prevent it from accessing the local filesystem. Therefore emscripten simulates a filesystem so that C/C++ code can be written normally, as if there were direct access to files. Note: if you want to run in a shell environment using node without sandboxing, then you can let code directly access the local filesystem using NODEFS, see :ref:`Filesystem-API`. +.. _packaging-files: + Packaging files =============== diff --git a/site/source/docs/site/about.rst b/site/source/docs/site/about.rst index 644f07b2ce683..03383b62c3c28 100644 --- a/site/source/docs/site/about.rst +++ b/site/source/docs/site/about.rst @@ -96,18 +96,13 @@ SDK Builds SDK builds are virtually identical to :ref:`about-site-builds`. The main difference is that on SDK builds the :ref:`home page ` has a clear notification that it is an SDK build. -SDK builds are enabled by adding the ``sdkbuild`` tag in `conf.py `_: :: - - #The line below must be uncommented for SDK builds. - tags.add('sdkbuild') - - -.. note:: In theory it should be possible to supply the ``sdkbuild`` tag as a command line option as shown below. However this is not working: - - :: - - make html SPHINXOPTS="-t sdkbuild" +SDK builds are enabled by enabling the ``sdkbuild`` tag. This is done through the ``SPHINXOPTS`` environment variable: :: + # Set the sdkbuild tag. + set SPHINXOPTS=-t sdkbuild + make html + # Unset SPHINXOPTS + set SPHINXOPTS= .. _about-build-versions: @@ -118,12 +113,16 @@ The documentation version should match the Emscripten version for the current bu The version and release information is used in a few places in the documentation, for example :ref:`emscripten-authors`. -The version is set in `conf.py `_ in the ``version`` and ``release`` values. For example: :: - # The short X.Y version. - version = '1.23' - # The full version, including alpha/beta/rc tags. - release = '1.23.0' + +The version can be ``version`` and ``release`` variables in **conf.py**, or on the command line by setting new values for these variables in the ``SPHINXOPTS`` environment variable. For example, to update the ``release`` variable through the command line: :: + + # Set SPHINXOPTS + set SPHINXOPTS=-D release=6.40 + make html + # Unset SPHINXOPTS + set SPHINXOPTS= + .. _writing-and-updating-articles: diff --git a/site/source/docs/tools_reference/emcc.rst b/site/source/docs/tools_reference/emcc.rst index 1e6d533c0b002..dc39f51d8f384 100644 --- a/site/source/docs/tools_reference/emcc.rst +++ b/site/source/docs/tools_reference/emcc.rst @@ -91,6 +91,8 @@ Options that are modified or new in *emcc* are listed below: The contents of **/path/to/file** will be read, JSON.parsed and set into ``DEAD_FUNCTIONS`` (so the file could contain ["_func1", "func2"] ). Note that the path must be absolute, not relative. +.. _emcc-g: + ``-g`` Use debug info. @@ -153,7 +155,9 @@ Options that are modified or new in *emcc* are listed below: - If LLVM optimizations are not run (see ``--llvm-opts``), this setting has no effect. - LLVM LTO is not perfectly stable yet, and can can cause code to behave incorrectly. - . + +.. _emcc-closure: + ``--closure `` Runs the :term:`Closure Compiler`. Possible ``on`` values are: @@ -249,7 +253,9 @@ Options that are modified or new in *emcc* are listed below: Tells the compiler to ignore dynamic linking (the user will need to manually link to the shared libraries later on). Normally *emcc* will simply link in code from the dynamic library as though it were statically linked, which will fail if the same dynamic library is linked more than once. With this option, dynamic linking is ignored, which allows the build system to proceed without errors. - + +.. _emcc-js-library: + ``--js-library `` A JavaScript library to use in addition to those in Emscripten's core libraries (src/library_*). @@ -269,7 +275,9 @@ Options that are modified or new in *emcc* are listed below: ``--save-bc PATH`` When compiling to JavaScript or HTML, this option will save a copy of the bitcode to the specified path. The bitcode will include all files being linked after link-time optimizations have been performed (if any), including standard libraries. - + +.. _emcc-memory-init-file: + ``--memory-init-file `` Specifies whether to emit a separate memory initialization file. Possible ``on`` values are: diff --git a/site/source/docs/tools_reference/emsdk.rst b/site/source/docs/tools_reference/emsdk.rst index 11fed04b62a71..05d70b5a9cb12 100644 --- a/site/source/docs/tools_reference/emsdk.rst +++ b/site/source/docs/tools_reference/emsdk.rst @@ -78,6 +78,7 @@ A particular installed SDK (or tool) can then be set as :term:`active Date: Mon, 25 Aug 2014 13:01:34 +0300 Subject: [PATCH 36/60] Fix native OSX builds in test_sockets.py. For OSX, when our own-compiled fastcomp Clang is invoked to build a native executable, we must pass a command line parameter to it to tell which OSX SDK we are targeting. --- tests/test_browser.py | 2 +- tests/test_sockets.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/test_browser.py b/tests/test_browser.py index aac4a0fa81311..57922e9882dd1 100644 --- a/tests/test_browser.py +++ b/tests/test_browser.py @@ -1344,7 +1344,7 @@ def test_glgears(self): message='You should see animating gears.') def test_glgears_long(self): - for proxy in [0, 1]: + for proxy in [0]: print 'proxy', proxy self.btest('hello_world_gles.c', expected=map(str, range(30, 500)), args=['-DHAVE_BUILTIN_SINCOS', '-DLONGTEST'] + (['--proxy-to-worker'] if proxy else [])) diff --git a/tests/test_sockets.py b/tests/test_sockets.py index 7226044f94f96..7e248e22b2fc3 100644 --- a/tests/test_sockets.py +++ b/tests/test_sockets.py @@ -48,7 +48,7 @@ def __enter__(self): # NOTE empty filename support is a hack to support # the current test_enet if self.filename: - Popen([CLANG_CC, path_from_root('tests', self.filename), '-o', 'server', '-DSOCKK=%d' % self.target_port] + self.args).communicate() + Popen([CLANG_CC, path_from_root('tests', self.filename), '-o', 'server', '-DSOCKK=%d' % self.target_port] + get_clang_native_args() + self.args).communicate() process = Popen([os.path.abspath('server')]) self.pids.append(process.pid) From 5b807a097b751f73aa37ecf203c4473fd7a0d9f3 Mon Sep 17 00:00:00 2001 From: Jukka Jylanki Date: Mon, 25 Aug 2014 13:57:45 +0300 Subject: [PATCH 37/60] Fix bad signature of emscripten_set_socket_error_callback() in emscripten.h --- system/include/emscripten/emscripten.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system/include/emscripten/emscripten.h b/system/include/emscripten/emscripten.h index cc727318cc2e1..bfe9ae588b673 100644 --- a/system/include/emscripten/emscripten.h +++ b/system/include/emscripten/emscripten.h @@ -77,7 +77,7 @@ extern void emscripten_cancel_main_loop(void); typedef void (*em_socket_callback)(int fd, void *userData); typedef void (*em_socket_error_callback)(int fd, int err, const char* msg, void *userData); -extern void emscripten_set_socket_error_callback(void *userData, em_socket_error_callback *callback); +extern void emscripten_set_socket_error_callback(void *userData, em_socket_error_callback callback); extern void emscripten_set_socket_open_callback(void *userData, em_socket_callback callback); extern void emscripten_set_socket_listen_callback(void *userData, em_socket_callback callback); extern void emscripten_set_socket_connection_callback(void *userData, em_socket_callback callback); From ff01ebc7de34e8d6fab6a677d3b10ba14ca86e08 Mon Sep 17 00:00:00 2001 From: Jukka Jylanki Date: Mon, 25 Aug 2014 14:04:35 +0300 Subject: [PATCH 38/60] Silence a lot of the absolute path include warnings by always accepting any path that has the directory emscripten in it. --- emcc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/emcc b/emcc index 65c9906088f31..5f17aa0bcd27f 100755 --- a/emcc +++ b/emcc @@ -419,6 +419,10 @@ try: valid_abspaths = [] def is_valid_abspath(path_name): + # Any path that is underneath the emscripten repository root must be ok. + if '/emscripten/' in path_name.replace('\\', '/'): + return True + for valid_abspath in valid_abspaths: if in_directory(valid_abspath, path_name): return True From df164a7910d3cf4e8fa9f2988ec0c8d4204de263 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jukka=20Jyl=C3=A4nki?= Date: Thu, 31 Jul 2014 15:12:29 +0300 Subject: [PATCH 39/60] Remove support for old Mozilla Audio Data API which is not longer available in Firefox. --- src/library_sdl.js | 147 ++++++++++++++++----------------------------- 1 file changed, 52 insertions(+), 95 deletions(-) diff --git a/src/library_sdl.js b/src/library_sdl.js index 5836d972abef2..db9f235641066 100644 --- a/src/library_sdl.js +++ b/src/library_sdl.js @@ -2157,116 +2157,73 @@ var LibrarySDL = { }; SDL.audio.audioOutput = new Audio(); - // As a workaround use Mozilla Audio Data API on Firefox until it ships with Web Audio and sound quality issues are fixed. - if (typeof(SDL.audio.audioOutput['mozSetup'])==='function') { - SDL.audio.audioOutput['mozSetup'](SDL.audio.channels, SDL.audio.freq); // use string attributes on mozOutput for closure compiler - SDL.audio.mozBuffer = new Float32Array(totalSamples); - SDL.audio.nextPlayTime = 0; - SDL.audio.pushAudio = function SDL_audio_pushAudio(ptr, size) { + + // Initialize Web Audio API if we haven't done so yet. Note: Only initialize Web Audio context ever once on the web page, + // since initializing multiple times fails on Chrome saying 'audio resources have been exhausted'. + SDL.openAudioContext(); + if (!SDL.audioContext) throw 'Web Audio API is not available!'; + SDL.audio.soundSource = new Array(); // Use an array of sound sources as a ring buffer to queue blocks of synthesized audio to Web Audio API. + SDL.audio.nextSoundSource = 0; // Index of the next sound buffer in the ring buffer queue to play. + SDL.audio.nextPlayTime = 0; // Time in seconds when the next audio block is due to start. + + // The pushAudio function with a new audio buffer whenever there is new audio data to schedule to be played back on the device. + SDL.audio.pushAudio=function(ptr,sizeBytes) { + try { --SDL.audio.numAudioTimersPending; - var mozBuffer = SDL.audio.mozBuffer; - // The input audio data for SDL audio is either 8-bit or 16-bit interleaved across channels, output for Mozilla Audio Data API - // needs to be Float32 interleaved, so perform a sample conversion. - if (SDL.audio.format == 0x8010 /*AUDIO_S16LSB*/) { - for (var i = 0; i < totalSamples; i++) { - mozBuffer[i] = ({{{ makeGetValue('ptr', 'i*2', 'i16', 0, 0) }}}) / 0x8000; - } - } else if (SDL.audio.format == 0x0008 /*AUDIO_U8*/) { - for (var i = 0; i < totalSamples; i++) { - var v = ({{{ makeGetValue('ptr', 'i', 'i8', 0, 0) }}}); - mozBuffer[i] = ((v >= 0) ? v-128 : v+128) /128; - } + if (SDL.audio.paused) return; + + var sizeSamples = sizeBytes / SDL.audio.bytesPerSample; // How many samples fit in the callback buffer? + var sizeSamplesPerChannel = sizeSamples / SDL.audio.channels; // How many samples per a single channel fit in the cb buffer? + if (sizeSamplesPerChannel != SDL.audio.samples) { + throw 'Received mismatching audio buffer size!'; } - // Submit the audio data to audio device. - SDL.audio.audioOutput['mozWriteAudio'](mozBuffer); + // Allocate new sound buffer to be played. + var source = SDL.audioContext['createBufferSource'](); + if (SDL.audio.soundSource[SDL.audio.nextSoundSource]) { + SDL.audio.soundSource[SDL.audio.nextSoundSource]['disconnect'](); // Explicitly disconnect old source, since we know it shouldn't be running anymore. + } + SDL.audio.soundSource[SDL.audio.nextSoundSource] = source; + var soundBuffer = SDL.audioContext['createBuffer'](SDL.audio.channels,sizeSamplesPerChannel,SDL.audio.freq); + SDL.audio.soundSource[SDL.audio.nextSoundSource]['connect'](SDL.audioContext['destination']); + + SDL.fillWebAudioBufferFromHeap(ptr, sizeSamplesPerChannel, soundBuffer); + // Workaround https://bugzilla.mozilla.org/show_bug.cgi?id=883675 by setting the buffer only after filling. The order is important here! + source['buffer'] = soundBuffer; - // Compute when the next audio callback should be called. - var curtime = Date.now() / 1000.0 - SDL.audio.startTime; + // Schedule the generated sample buffer to be played out at the correct time right after the previously scheduled + // sample buffer has finished. + var curtime = SDL.audioContext['currentTime']; #if ASSERTIONS if (curtime > SDL.audio.nextPlayTime && SDL.audio.nextPlayTime != 0) { console.log('warning: Audio callback had starved sending audio by ' + (curtime - SDL.audio.nextPlayTime) + ' seconds.'); } #endif var playtime = Math.max(curtime, SDL.audio.nextPlayTime); - var buffer_duration = SDL.audio.samples / SDL.audio.freq; + var ss = SDL.audio.soundSource[SDL.audio.nextSoundSource]; + if (typeof ss['start'] !== 'undefined') { + ss['start'](playtime); + } else if (typeof ss['noteOn'] !== 'undefined') { + ss['noteOn'](playtime); + } + var buffer_duration = sizeSamplesPerChannel / SDL.audio.freq; SDL.audio.nextPlayTime = playtime + buffer_duration; - // Schedule the next audio callback call to occur when the current one finishes. - SDL.audio.timer = Browser.safeSetTimeout(SDL.audio.caller, 1000.0 * (playtime-curtime)); + // Timer will be scheduled before the buffer completed playing. + // Extra buffers are needed to avoid disturbing playing buffer. + SDL.audio.nextSoundSource = (SDL.audio.nextSoundSource + 1) % (SDL.audio.numSimultaneouslyQueuedBuffers + 2); + var secsUntilNextCall = playtime-curtime; + + // Queue the next audio frame push to be performed when the previously queued buffer has finished playing. + var preemptBufferFeedMSecs = 1000*buffer_duration/2.0; + SDL.audio.timer = Browser.safeSetTimeout(SDL.audio.caller, Math.max(0.0, 1000.0*secsUntilNextCall-preemptBufferFeedMSecs)); ++SDL.audio.numAudioTimersPending; - // And also schedule extra buffers _now_ if we have too few in queue. + + // If we are risking starving, immediately queue extra buffers. if (SDL.audio.numAudioTimersPending < SDL.audio.numSimultaneouslyQueuedBuffers) { ++SDL.audio.numAudioTimersPending; Browser.safeSetTimeout(SDL.audio.caller, 1.0); } - } - } else { - // Initialize Web Audio API if we haven't done so yet. Note: Only initialize Web Audio context ever once on the web page, - // since initializing multiple times fails on Chrome saying 'audio resources have been exhausted'. - SDL.openAudioContext(); - if (!SDL.audioContext) throw 'Web Audio API is not available!'; - SDL.audio.soundSource = new Array(); // Use an array of sound sources as a ring buffer to queue blocks of synthesized audio to Web Audio API. - SDL.audio.nextSoundSource = 0; // Index of the next sound buffer in the ring buffer queue to play. - SDL.audio.nextPlayTime = 0; // Time in seconds when the next audio block is due to start. - - // The pushAudio function with a new audio buffer whenever there is new audio data to schedule to be played back on the device. - SDL.audio.pushAudio=function(ptr,sizeBytes) { - try { - --SDL.audio.numAudioTimersPending; - if (SDL.audio.paused) return; - - var sizeSamples = sizeBytes / SDL.audio.bytesPerSample; // How many samples fit in the callback buffer? - var sizeSamplesPerChannel = sizeSamples / SDL.audio.channels; // How many samples per a single channel fit in the cb buffer? - if (sizeSamplesPerChannel != SDL.audio.samples) { - throw 'Received mismatching audio buffer size!'; - } - // Allocate new sound buffer to be played. - var source = SDL.audioContext['createBufferSource'](); - if (SDL.audio.soundSource[SDL.audio.nextSoundSource]) { - SDL.audio.soundSource[SDL.audio.nextSoundSource]['disconnect'](); // Explicitly disconnect old source, since we know it shouldn't be running anymore. - } - SDL.audio.soundSource[SDL.audio.nextSoundSource] = source; - var soundBuffer = SDL.audioContext['createBuffer'](SDL.audio.channels,sizeSamplesPerChannel,SDL.audio.freq); - SDL.audio.soundSource[SDL.audio.nextSoundSource]['connect'](SDL.audioContext['destination']); - - SDL.fillWebAudioBufferFromHeap(ptr, sizeSamplesPerChannel, soundBuffer); - // Workaround https://bugzilla.mozilla.org/show_bug.cgi?id=883675 by setting the buffer only after filling. The order is important here! - source['buffer'] = soundBuffer; - - // Schedule the generated sample buffer to be played out at the correct time right after the previously scheduled - // sample buffer has finished. - var curtime = SDL.audioContext['currentTime']; -#if ASSERTIONS - if (curtime > SDL.audio.nextPlayTime && SDL.audio.nextPlayTime != 0) { - console.log('warning: Audio callback had starved sending audio by ' + (curtime - SDL.audio.nextPlayTime) + ' seconds.'); - } -#endif - var playtime = Math.max(curtime, SDL.audio.nextPlayTime); - var ss = SDL.audio.soundSource[SDL.audio.nextSoundSource]; - if (typeof ss['start'] !== 'undefined') { - ss['start'](playtime); - } else if (typeof ss['noteOn'] !== 'undefined') { - ss['noteOn'](playtime); - } - var buffer_duration = sizeSamplesPerChannel / SDL.audio.freq; - SDL.audio.nextPlayTime = playtime + buffer_duration; - // Timer will be scheduled before the buffer completed playing. - // Extra buffers are needed to avoid disturbing playing buffer. - SDL.audio.nextSoundSource = (SDL.audio.nextSoundSource + 1) % (SDL.audio.numSimultaneouslyQueuedBuffers + 2); - var secsUntilNextCall = playtime-curtime; - - // Queue the next audio frame push to be performed when the previously queued buffer has finished playing. - var preemptBufferFeedMSecs = 1000*buffer_duration/2.0; - SDL.audio.timer = Browser.safeSetTimeout(SDL.audio.caller, Math.max(0.0, 1000.0*secsUntilNextCall-preemptBufferFeedMSecs)); - ++SDL.audio.numAudioTimersPending; - - // If we are risking starving, immediately queue extra buffers. - if (SDL.audio.numAudioTimersPending < SDL.audio.numSimultaneouslyQueuedBuffers) { - ++SDL.audio.numAudioTimersPending; - Browser.safeSetTimeout(SDL.audio.caller, 1.0); - } - } catch(e) { - console.log('Web Audio API error playing back audio: ' + e.toString()); - } + } catch(e) { + console.log('Web Audio API error playing back audio: ' + e.toString()); } } From 9440047e4b99425032874d870683ca4a3c833e35 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jukka=20Jyl=C3=A4nki?= Date: Thu, 31 Jul 2014 15:25:49 +0300 Subject: [PATCH 40/60] Remove the use of Web Audio API ScriptProcessorNode for queueing buffers. It doesn't improve in practice, generates a new set of compatibility bugs and is limited to one sampling frequency only (which the browser either matches or doesn't match at random). Keep the code simple and use a unified path for SDL audio in all audio frequencies. --- src/library_sdl.js | 26 +++++--------------------- 1 file changed, 5 insertions(+), 21 deletions(-) diff --git a/src/library_sdl.js b/src/library_sdl.js index db9f235641066..51d351c9c4450 100644 --- a/src/library_sdl.js +++ b/src/library_sdl.js @@ -2269,27 +2269,11 @@ var LibrarySDL = { SDL.audio.numAudioTimersPending = 0; SDL.audio.timer = undefined; } - if (SDL.audio.scriptProcessorNode !== undefined) { - SDL.audio.scriptProcessorNode['disconnect'](); - SDL.audio.scriptProcessorNode = undefined; - } - } else if (!SDL.audio.timer && !SDL.audio.scriptProcessorNode) { - // If we are using the same sampling frequency as the native sampling rate of the Web Audio graph is using, we can feed our buffers via - // Web Audio ScriptProcessorNode, which is a pull-mode API that calls back to our code to get audio data. - if (SDL.audioContext !== undefined && SDL.audio.freq == SDL.audioContext['sampleRate'] && typeof SDL.audioContext['createScriptProcessor'] !== 'undefined') { - var sizeSamplesPerChannel = SDL.audio.bufferSize / SDL.audio.bytesPerSample / SDL.audio.channels; // How many samples per a single channel fit in the cb buffer? - SDL.audio.scriptProcessorNode = SDL.audioContext['createScriptProcessor'](sizeSamplesPerChannel, 0, SDL.audio.channels); - SDL.audio.scriptProcessorNode['onaudioprocess'] = function (e) { - Runtime.dynCall('viii', SDL.audio.callback, [SDL.audio.userdata, SDL.audio.buffer, SDL.audio.bufferSize]); - SDL.fillWebAudioBufferFromHeap(SDL.audio.buffer, sizeSamplesPerChannel, e['outputBuffer']); - } - SDL.audio.scriptProcessorNode['connect'](SDL.audioContext['destination']); - } else { // If we are using a different sampling rate, must manually queue audio data to the graph via timers. - // Start the audio playback timer callback loop. - SDL.audio.numAudioTimersPending = 1; - SDL.audio.timer = Browser.safeSetTimeout(SDL.audio.caller, 1); - SDL.audio.startTime = Date.now() / 1000.0; // Only used for Mozilla Audio Data API. Not needed for Web Audio API. - } + } else if (!SDL.audio.timer) { + // Start the audio playback timer callback loop. + SDL.audio.numAudioTimersPending = 1; + SDL.audio.timer = Browser.safeSetTimeout(SDL.audio.caller, 1); + SDL.audio.startTime = Date.now() / 1000.0; // Only used for Mozilla Audio Data API. Not needed for Web Audio API. } SDL.audio.paused = pauseOn; }, From 844929b805564bb99a006655b063e155cc4218a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jukka=20Jyl=C3=A4nki?= Date: Thu, 31 Jul 2014 17:29:57 +0300 Subject: [PATCH 41/60] Improve SDL audio queueing to not only rely on setTimeout()s to queue new audio data, but also try to queue new audio at the end of each requestAnimationFrame. Since rAFs fire at every 16 msecs tied to vsync interval, this should give a much better granularity for audio streaming. --- src/library_browser.js | 3 ++ src/library_sdl.js | 112 ++++++++++++++++++++++++----------------- 2 files changed, 68 insertions(+), 47 deletions(-) diff --git a/src/library_browser.js b/src/library_browser.js index e362bb589b973..df6f8d5fc5568 100644 --- a/src/library_browser.js +++ b/src/library_browser.js @@ -1010,6 +1010,9 @@ mergeInto(LibraryManager.library, { } }); + // Queue new audio data. + if (SDL && SDL.audio && SDL.audio.queueNewAudioData) SDL.audio.queueNewAudioData(); + if (Browser.mainLoop.shouldPause) { // catch pauses from the main loop itself Browser.mainLoop.paused = true; diff --git a/src/library_sdl.js b/src/library_sdl.js index 51d351c9c4450..c44ba87bcd7a9 100644 --- a/src/library_sdl.js +++ b/src/library_sdl.js @@ -1036,7 +1036,7 @@ var LibrarySDL = { } }, - // Pausea an SDL audio resource that was played with Web Audio.. + // Pauses an SDL audio resource that was played with Web Audio. pauseWebAudio: function(audio) { if (!audio) return; if (audio.webAudioNode) { @@ -2141,19 +2141,59 @@ var LibrarySDL = { var totalSamples = SDL.audio.samples*SDL.audio.channels; SDL.audio.bytesPerSample = (SDL.audio.format == 0x0008 /*AUDIO_U8*/ || SDL.audio.format == 0x8008 /*AUDIO_S8*/) ? 1 : 2; SDL.audio.bufferSize = totalSamples*SDL.audio.bytesPerSample; + SDL.audio.bufferDurationSecs = SDL.audio.bufferSize / SDL.audio.bytesPerSample / SDL.audio.channels / SDL.audio.freq; // Duration of a single queued buffer in seconds. + SDL.audio.bufferingDelay = 150 / 1000; // Audio samples are played with a constant delay of this many seconds to account for browser and jitter. SDL.audio.buffer = _malloc(SDL.audio.bufferSize); // To account for jittering in frametimes, always have multiple audio buffers queued up for the audio output device. // This helps that we won't starve that easily if a frame takes long to complete. - SDL.audio.numSimultaneouslyQueuedBuffers = Module['SDL_numSimultaneouslyQueuedBuffers'] || 3; - + SDL.audio.numSimultaneouslyQueuedBuffers = Module['SDL_numSimultaneouslyQueuedBuffers'] || 5; + + // Pulls and queues new audio data if appropriate. This function gets "over-called" in both requestAnimationFrames and + // setTimeouts to ensure that we get the finest granularity possible and as many chances from the browser to fill + // new audio data. This is because setTimeouts alone have very poor granularity for audio streaming purposes, but also + // the application might not be using emscripten_set_main_loop to drive the main loop, so we cannot rely on that alone. + SDL.audio.queueNewAudioData = function SDL_queueNewAudioData() { + if (!SDL.audio) return; + + var secsUntilNextPlayStart = SDL.audio.nextPlayTime - SDL.audioContext['currentTime']; + + for(var i = 0; i < SDL.audio.numSimultaneouslyQueuedBuffers; ++i) { + // Only queue new data if we don't have enough audio data already in queue. Otherwise skip this time slot + // and wait to queue more in the next time the callback is run. + if (secsUntilNextPlayStart >= SDL.audio.bufferingDelay + SDL.audio.bufferDurationSecs*SDL.audio.numSimultaneouslyQueuedBuffers) return; + + // Ask SDL audio data from the user code. + Runtime.dynCall('viii', SDL.audio.callback, [SDL.audio.userdata, SDL.audio.buffer, SDL.audio.bufferSize]); + // And queue it to be played after the currently playing audio stream. + SDL.audio.pushAudio(SDL.audio.buffer, SDL.audio.bufferSize); + } + } + // Create a callback function that will be routinely called to ask more audio data from the user application. - SDL.audio.caller = function SDL_audio_caller() { - if (!SDL.audio) { - return; + SDL.audio.caller = function SDL_audioCaller() { + if (!SDL.audio) return; + + --SDL.audio.numAudioTimersPending; + + SDL.audio.queueNewAudioData(); + + // Queue this callback function to be called again later to pull more audio data. + var secsUntilNextPlayStart = SDL.audio.nextPlayTime - SDL.audioContext['currentTime']; + + // Queue the next audio frame push to be performed half-way when the previously queued buffer has finished playing. + var preemptBufferFeedSecs = SDL.audio.bufferDurationSecs/2.0; + + if (SDL.audio.numAudioTimersPending < SDL.audio.numSimultaneouslyQueuedBuffers) { + ++SDL.audio.numAudioTimersPending; + SDL.audio.timer = Browser.safeSetTimeout(SDL.audio.caller, Math.max(0.0, 1000.0*(secsUntilNextPlayStart-preemptBufferFeedSecs))); + + // If we are risking starving, immediately queue an extra buffer. + if (SDL.audio.numAudioTimersPending < SDL.audio.numSimultaneouslyQueuedBuffers) { + ++SDL.audio.numAudioTimersPending; + Browser.safeSetTimeout(SDL.audio.caller, 1.0); + } } - Runtime.dynCall('viii', SDL.audio.callback, [SDL.audio.userdata, SDL.audio.buffer, SDL.audio.bufferSize]); - SDL.audio.pushAudio(SDL.audio.buffer, SDL.audio.bufferSize); }; SDL.audio.audioOutput = new Audio(); @@ -2162,14 +2202,11 @@ var LibrarySDL = { // since initializing multiple times fails on Chrome saying 'audio resources have been exhausted'. SDL.openAudioContext(); if (!SDL.audioContext) throw 'Web Audio API is not available!'; - SDL.audio.soundSource = new Array(); // Use an array of sound sources as a ring buffer to queue blocks of synthesized audio to Web Audio API. - SDL.audio.nextSoundSource = 0; // Index of the next sound buffer in the ring buffer queue to play. SDL.audio.nextPlayTime = 0; // Time in seconds when the next audio block is due to start. // The pushAudio function with a new audio buffer whenever there is new audio data to schedule to be played back on the device. SDL.audio.pushAudio=function(ptr,sizeBytes) { try { - --SDL.audio.numAudioTimersPending; if (SDL.audio.paused) return; var sizeSamples = sizeBytes / SDL.audio.bytesPerSample; // How many samples fit in the callback buffer? @@ -2179,12 +2216,8 @@ var LibrarySDL = { } // Allocate new sound buffer to be played. var source = SDL.audioContext['createBufferSource'](); - if (SDL.audio.soundSource[SDL.audio.nextSoundSource]) { - SDL.audio.soundSource[SDL.audio.nextSoundSource]['disconnect'](); // Explicitly disconnect old source, since we know it shouldn't be running anymore. - } - SDL.audio.soundSource[SDL.audio.nextSoundSource] = source; var soundBuffer = SDL.audioContext['createBuffer'](SDL.audio.channels,sizeSamplesPerChannel,SDL.audio.freq); - SDL.audio.soundSource[SDL.audio.nextSoundSource]['connect'](SDL.audioContext['destination']); + source['connect'](SDL.audioContext['destination']); SDL.fillWebAudioBufferFromHeap(ptr, sizeSamplesPerChannel, soundBuffer); // Workaround https://bugzilla.mozilla.org/show_bug.cgi?id=883675 by setting the buffer only after filling. The order is important here! @@ -2198,30 +2231,24 @@ var LibrarySDL = { console.log('warning: Audio callback had starved sending audio by ' + (curtime - SDL.audio.nextPlayTime) + ' seconds.'); } #endif - var playtime = Math.max(curtime, SDL.audio.nextPlayTime); - var ss = SDL.audio.soundSource[SDL.audio.nextSoundSource]; - if (typeof ss['start'] !== 'undefined') { - ss['start'](playtime); - } else if (typeof ss['noteOn'] !== 'undefined') { - ss['noteOn'](playtime); + // Don't ever start buffer playbacks earlier from current time than a given constant 'SDL.audio.bufferingDelay', since a browser + // may not be able to mix that audio clip in immediately, and there may be subsequent jitter that might cause the stream to starve. + var playtime = Math.max(curtime + SDL.audio.bufferingDelay, SDL.audio.nextPlayTime); + if (typeof source['start'] !== 'undefined') { + source['start'](playtime); // New Web Audio API: sound sources are started with a .start() call. + } else if (typeof source['noteOn'] !== 'undefined') { + source['noteOn'](playtime); // Support old Web Audio API specification which had the .noteOn() API. } - var buffer_duration = sizeSamplesPerChannel / SDL.audio.freq; - SDL.audio.nextPlayTime = playtime + buffer_duration; - // Timer will be scheduled before the buffer completed playing. - // Extra buffers are needed to avoid disturbing playing buffer. - SDL.audio.nextSoundSource = (SDL.audio.nextSoundSource + 1) % (SDL.audio.numSimultaneouslyQueuedBuffers + 2); - var secsUntilNextCall = playtime-curtime; - - // Queue the next audio frame push to be performed when the previously queued buffer has finished playing. - var preemptBufferFeedMSecs = 1000*buffer_duration/2.0; - SDL.audio.timer = Browser.safeSetTimeout(SDL.audio.caller, Math.max(0.0, 1000.0*secsUntilNextCall-preemptBufferFeedMSecs)); - ++SDL.audio.numAudioTimersPending; - - // If we are risking starving, immediately queue extra buffers. - if (SDL.audio.numAudioTimersPending < SDL.audio.numSimultaneouslyQueuedBuffers) { - ++SDL.audio.numAudioTimersPending; - Browser.safeSetTimeout(SDL.audio.caller, 1.0); + /* + // Uncomment to debug SDL buffer feed starves. + if (SDL.audio.curBufferEnd) { + var thisBufferStart = Math.round(playtime * SDL.audio.freq); + if (thisBufferStart != SDL.audio.curBufferEnd) console.log('SDL starved ' + (thisBufferStart - SDL.audio.curBufferEnd) + ' samples!'); } + SDL.audio.curBufferEnd = Math.round(playtime * SDL.audio.freq + sizeSamplesPerChannel); + */ + + SDL.audio.nextPlayTime = playtime + SDL.audio.bufferDurationSecs; } catch(e) { console.log('Web Audio API error playing back audio: ' + e.toString()); } @@ -2273,7 +2300,6 @@ var LibrarySDL = { // Start the audio playback timer callback loop. SDL.audio.numAudioTimersPending = 1; SDL.audio.timer = Browser.safeSetTimeout(SDL.audio.caller, 1); - SDL.audio.startTime = Date.now() / 1000.0; // Only used for Mozilla Audio Data API. Not needed for Web Audio API. } SDL.audio.paused = pauseOn; }, @@ -2281,14 +2307,6 @@ var LibrarySDL = { SDL_CloseAudio__deps: ['SDL_PauseAudio', 'free'], SDL_CloseAudio: function() { if (SDL.audio) { - try{ - for(var i = 0; i < SDL.audio.soundSource.length; ++i) { - if (!(typeof(SDL.audio.soundSource[i]==='undefined'))) { - SDL.audio.soundSource[i].stop(0); - } - } - } catch(e) {} - SDL.audio.soundSource = null; _SDL_PauseAudio(1); _free(SDL.audio.buffer); SDL.audio = null; From d02db300693496dd083646a91fb4e72a013ef7d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jukka=20Jyl=C3=A4nki?= Date: Mon, 25 Aug 2014 15:10:33 +0300 Subject: [PATCH 42/60] Reduce the SDL buffering delay to 50msecs to make the audio latency smaller. --- src/library_browser.js | 7 +++++-- src/library_sdl.js | 2 +- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/src/library_browser.js b/src/library_browser.js index df6f8d5fc5568..18ff6a60ac213 100644 --- a/src/library_browser.js +++ b/src/library_browser.js @@ -1010,8 +1010,11 @@ mergeInto(LibraryManager.library, { } }); - // Queue new audio data. - if (SDL && SDL.audio && SDL.audio.queueNewAudioData) SDL.audio.queueNewAudioData(); + // Queue new audio data. This is important to be right after the main loop invocation, so that we will immediately be able + // to queue the newest produced audio samples. + // TODO: Consider adding pre- and post- rAF callbacks so that GL.newRenderingFrameStarted() and SDL.audio.queueNewAudioData() + // do not need to be hardcoded into this function, but can be more generic. + if (typeof SDL === 'object' && SDL.audio && SDL.audio.queueNewAudioData) SDL.audio.queueNewAudioData(); if (Browser.mainLoop.shouldPause) { // catch pauses from the main loop itself diff --git a/src/library_sdl.js b/src/library_sdl.js index c44ba87bcd7a9..bf6079e335234 100644 --- a/src/library_sdl.js +++ b/src/library_sdl.js @@ -2142,7 +2142,7 @@ var LibrarySDL = { SDL.audio.bytesPerSample = (SDL.audio.format == 0x0008 /*AUDIO_U8*/ || SDL.audio.format == 0x8008 /*AUDIO_S8*/) ? 1 : 2; SDL.audio.bufferSize = totalSamples*SDL.audio.bytesPerSample; SDL.audio.bufferDurationSecs = SDL.audio.bufferSize / SDL.audio.bytesPerSample / SDL.audio.channels / SDL.audio.freq; // Duration of a single queued buffer in seconds. - SDL.audio.bufferingDelay = 150 / 1000; // Audio samples are played with a constant delay of this many seconds to account for browser and jitter. + SDL.audio.bufferingDelay = 50 / 1000; // Audio samples are played with a constant delay of this many seconds to account for browser and jitter. SDL.audio.buffer = _malloc(SDL.audio.bufferSize); // To account for jittering in frametimes, always have multiple audio buffers queued up for the audio output device. From 1d71a32d71681042a6489ab24a3aa7c377f17593 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jukka=20Jyl=C3=A4nki?= Date: Mon, 25 Aug 2014 16:55:55 +0300 Subject: [PATCH 43/60] Optimize memory usage in library_gl.js to avoid unnecessary 2MB temp memory buffer from being created when neither FULL_ES2 or LEGACY_GL_EMULATION is defined. --- src/compiler.js | 4 ++++ src/library_browser.js | 5 +---- src/library_gl.js | 20 ++++++++------------ 3 files changed, 13 insertions(+), 16 deletions(-) diff --git a/src/compiler.js b/src/compiler.js index 9e062d6f0d096..ab2f4c3e394f5 100644 --- a/src/compiler.js +++ b/src/compiler.js @@ -171,6 +171,10 @@ EXPORTED_FUNCTIONS = set(EXPORTED_FUNCTIONS); EXPORTED_GLOBALS = set(EXPORTED_GLOBALS); EXCEPTION_CATCHING_WHITELIST = set(EXCEPTION_CATCHING_WHITELIST); +// TODO: Implement support for proper preprocessing, e.g. "#if A || B" and "#if defined(A) || defined(B)" to +// avoid needing this here. +USES_GL_EMULATION = FULL_ES2 || LEGACY_GL_EMULATION; + DEAD_FUNCTIONS.forEach(function(dead) { DEFAULT_LIBRARY_FUNCS_TO_INCLUDE.push(dead.substr(1)); }); diff --git a/src/library_browser.js b/src/library_browser.js index e362bb589b973..eebdec4cf630a 100644 --- a/src/library_browser.js +++ b/src/library_browser.js @@ -990,10 +990,7 @@ mergeInto(LibraryManager.library, { // Signal GL rendering layer that processing of a new frame is about to start. This helps it optimize // VBO double-buffering and reduce GPU stalls. -#if FULL_ES2 - GL.newRenderingFrameStarted(); -#endif -#if LEGACY_GL_EMULATION +#if USES_GL_EMULATION GL.newRenderingFrameStarted(); #endif diff --git a/src/library_gl.js b/src/library_gl.js index 466426e4a61f1..8d8db3c6e3767 100644 --- a/src/library_gl.js +++ b/src/library_gl.js @@ -22,11 +22,7 @@ var LibraryGL = { vaos: [], contexts: [], -#if FULL_ES2 - currArrayBuffer: 0, - currElementArrayBuffer: 0, -#endif -#if LEGACY_GL_EMULATION +#if USES_GL_EMULATION currArrayBuffer: 0, currElementArrayBuffer: 0, #endif @@ -58,7 +54,9 @@ var LibraryGL = { unpackAlignment: 4, // default alignment is 4 bytes init: function() { +#if USES_GL_EMULATION GL.createLog2ceilLookup(GL.MAX_TEMP_BUFFER_SIZE); +#endif GL.miniTempBuffer = new Float32Array(GL.MINI_TEMP_BUFFER_SIZE); for (var i = 0; i < GL.MINI_TEMP_BUFFER_SIZE; i++) { GL.miniTempBufferViews[i] = GL.miniTempBuffer.subarray(0, i+1); @@ -86,6 +84,7 @@ var LibraryGL = { miniTempBuffer: null, miniTempBufferViews: [0], // index i has the view of size i+1 +#if USES_GL_EMULATION // When user GL code wants to render from client-side memory, we need to upload the vertex data to a temp VBO // for rendering. Maintain a set of temp VBOs that are created-on-demand to appropriate sizes, and never destroyed. // Also, for best performance the VBOs are double-buffered, i.e. every second frame we switch the set of VBOs we @@ -212,6 +211,7 @@ var LibraryGL = { GL.currentContext.tempVertexBufferCounters1[i] = 0; } }, +#endif #if LEGACY_GL_EMULATION // Find a token in a shader source string @@ -1636,16 +1636,12 @@ var LibraryGL = { #endif var bufferObj = buffer ? GL.buffers[buffer] : null; -#if FULL_ES2 +#if USES_GL_EMULATION if (target == GLctx.ARRAY_BUFFER) { GL.currArrayBuffer = buffer; - } else if (target == GLctx.ELEMENT_ARRAY_BUFFER) { - GL.currElementArrayBuffer = buffer; - } -#endif #if LEGACY_GL_EMULATION - if (target == GLctx.ARRAY_BUFFER) { - GLImmediate.lastArrayBuffer = GL.currArrayBuffer = buffer; + GLImmediate.lastArrayBuffer = buffer; +#endif } else if (target == GLctx.ELEMENT_ARRAY_BUFFER) { GL.currElementArrayBuffer = buffer; } From 63614dce21aab5f069d52997b738ab16655006a1 Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Fri, 22 Aug 2014 17:00:37 -0700 Subject: [PATCH 44/60] improve warning --- emcc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/emcc b/emcc index 5f17aa0bcd27f..d44314811cdc7 100755 --- a/emcc +++ b/emcc @@ -927,7 +927,7 @@ try: shared.Settings.CLOSURE_COMPILER = closure assert os.path.exists(shared.CLOSURE_COMPILER), logging.error('fatal: Closure compiler (%s) does not exist', shared.CLOSURE_COMPILER) if closure == 2 and shared.Settings.ASM_JS == 1: - logging.warning('not all asm.js optimizations are possible with --closure 2, disabling those') + logging.warning('not all asm.js optimizations are possible with --closure 2, disabling those - your code will be run more slowly') shared.Settings.ASM_JS = 2 assert shared.LLVM_TARGET in shared.COMPILER_OPTS From f9ca07efa03a28f812df0dea653bd01dc66c7287 Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Mon, 25 Aug 2014 10:49:49 -0700 Subject: [PATCH 45/60] make test_source_map more robust --- tests/test_core.py | 1 + 1 file changed, 1 insertion(+) diff --git a/tests/test_core.py b/tests/test_core.py index c5056649f30a0..400631efcc868 100644 --- a/tests/test_core.py +++ b/tests/test_core.py @@ -6537,6 +6537,7 @@ def build_and_check(): out_file = re.sub(' *//[@#].*$', '', out_file, flags=re.MULTILINE) def clean(code): code = re.sub(r'\n+[ \n]*\n+', '\n', code) + code = re.sub(' L\d+ ?:', '', code) # ignore labels; they can change in each compile code = code.replace('{\n}', '{}') lines = code.split('\n') lines = filter(lambda line: ': do {' not in line and ' break L' not in line, lines) # ignore labels; they can change in each compile From 11a49ee9459cadb8e0744b6383dcc26ae41ad95a Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Mon, 25 Aug 2014 11:17:01 -0700 Subject: [PATCH 46/60] add more test coverage for source maps, and improve existing test --- tests/test_core.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/tests/test_core.py b/tests/test_core.py index 400631efcc868..ae0424189f060 100644 --- a/tests/test_core.py +++ b/tests/test_core.py @@ -5215,6 +5215,10 @@ def test_zlib(self): if self.emcc_args is not None and '-O2' in self.emcc_args and 'ASM_JS=0' not in self.emcc_args: # without asm, closure minifies Math.imul badly self.emcc_args += ['--closure', '1'] # Use closure here for some additional coverage + assert 'asm2g' in test_modes + if self.run_name == 'asm2g': + self.emcc_args += ['-g4'] # more source maps coverage + Settings.CORRECT_SIGNS = 1 self.do_run(open(path_from_root('tests', 'zlib', 'example.c'), 'r').read(), @@ -6536,6 +6540,7 @@ def build_and_check(): # optimizer can deal with both types. out_file = re.sub(' *//[@#].*$', '', out_file, flags=re.MULTILINE) def clean(code): + code = re.sub(';', ';\n', code) # put statements each on a new line code = re.sub(r'\n+[ \n]*\n+', '\n', code) code = re.sub(' L\d+ ?:', '', code) # ignore labels; they can change in each compile code = code.replace('{\n}', '{}') From ffb887d170000f64250c9ce4aca4e8661d677957 Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Mon, 25 Aug 2014 11:17:09 -0700 Subject: [PATCH 47/60] add a newline to source comments in uglify, where necessary --- tools/eliminator/node_modules/uglify-js/lib/process.js | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/tools/eliminator/node_modules/uglify-js/lib/process.js b/tools/eliminator/node_modules/uglify-js/lib/process.js index e1d692b2cc00e..d75ab18aa474f 100644 --- a/tools/eliminator/node_modules/uglify-js/lib/process.js +++ b/tools/eliminator/node_modules/uglify-js/lib/process.js @@ -1752,7 +1752,15 @@ function gen_code(ast, options) { }, "stat": function(stmt) { var str = make(stmt); - return str.replace(/;*\s*$/, ";") + str.lineComment(); + var comment = str.lineComment(); + str = str.replace(/;*\s*$/, ";"); + if (comment) { + if (comment.indexOf('//') >= 0 && comment.indexOf('\n') < 0) { + comment = comment + '\n'; // we need a newline here, as the "//" may remove other things shown on the same line as this stat + } + return str + comment; + } + return str; }, "seq": function() { return add_commas(MAP(slice(arguments), make)); From 7cf41ca233cc3d075c3d08d07e0747e3338b78f5 Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Fri, 22 Aug 2014 17:09:18 -0700 Subject: [PATCH 48/60] remove unnecessary curly braces around all one-line blocks, where possible --- tools/js-optimizer.js | 7 +++- tools/test-js-optimizer-asm-last-output.js | 47 ++++++++-------------- tools/test-js-optimizer-asm-last.js | 5 +++ 3 files changed, 28 insertions(+), 31 deletions(-) diff --git a/tools/js-optimizer.js b/tools/js-optimizer.js index dfee80c3e43d4..566f5ed293b42 100644 --- a/tools/js-optimizer.js +++ b/tools/js-optimizer.js @@ -5626,7 +5626,7 @@ function asmLastOpts(ast) { node[1] = simplifyNotCompsDirect(['unary-prefix', '!', conditionToBreak]); return node; } - } else if (type == 'binary') { + } else if (type === 'binary') { if (node[1] === '&') { if (node[3][0] === 'unary-prefix' && node[3][1] === '-' && node[3][2][0] === 'num' && node[3][2][1] === 1) { // Change &-1 into |0, at this point the hint is no longer needed @@ -5652,6 +5652,11 @@ function asmLastOpts(ast) { var stats = getStatements(node); if (stats) statsStack.pop(); }); + traverse(fun, function(node, type) { + if (type === 'block' && node[1] && node[1].length === 1) { + return node[1][0]; + } + }); }); } diff --git a/tools/test-js-optimizer-asm-last-output.js b/tools/test-js-optimizer-asm-last-output.js index 95afaeb7a0b29..1d1b03fb7b27a 100644 --- a/tools/test-js-optimizer-asm-last-output.js +++ b/tools/test-js-optimizer-asm-last-output.js @@ -35,46 +35,28 @@ function finall(x) { return 12.0e10; } function looop() { - do { - do_it(); - } while (!condition()); - do { - do_it(); - } while (!(a > b)); - do { - do_it(); - } while (x()); + do do_it(); while (!condition()); + do do_it(); while (!(a > b)); + do do_it(); while (x()); while (1) { do_it(); if (a()) continue; - if (!x()) { - break; - } + if (!x()) break; } do { do_it(); - do { - if (a()) continue; - } while (b()); + do if (a()) continue; while (b()); } while (x()); do { do_it(); - while (b()) { - if (a()) continue; - } + while (b()) if (a()) continue; } while (x()); X : while (1) { do_it(); - while (b()) { - if (a()) continue X; - } - if (!x()) { - break; - } + while (b()) if (a()) continue X; + if (!x()) break; } - do { - blah(); - } while (!shah()); + do blah(); while (!shah()); a = b; LABELED : while (1) { blah(); @@ -93,10 +75,15 @@ function looop() { } do { blah(); - while (1) { - if (check) break; - } + while (1) if (check) break; } while (!shah()); g = h; + if (a) waka(); + if (a) waka(); else wala(); + if (a) if (a) waka(); else wala(); + if (a) { + if (a) waka(); + } else other(); + if (a) if (a) waka(); else wala(); else other(); } diff --git a/tools/test-js-optimizer-asm-last.js b/tools/test-js-optimizer-asm-last.js index 6261e9158ad3e..f6609731cf585 100644 --- a/tools/test-js-optimizer-asm-last.js +++ b/tools/test-js-optimizer-asm-last.js @@ -119,6 +119,11 @@ function looop() { break; } } + if (a) { waka(); } + if (a) { waka(); } else { wala(); } + if (a) { if (a) { waka(); } else { wala(); } } + if (a) { if (a) { waka(); } } else { other(); } + if (a) { if (a) { waka(); } else { wala(); } } else { other(); } } // EMSCRIPTEN_GENERATED_FUNCTIONS: ["finall", "looop"] From 6fdc3e973d9395941a273b440dfabb1b1ab70797 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jukka=20Jyl=C3=A4nki?= Date: Tue, 26 Aug 2014 00:14:45 +0300 Subject: [PATCH 49/60] Revert bad code change from https://github.com/kripken/emscripten/commit/5bed7c1a052c3a995a67d42a12596d424c4ec48a which accidentally removed proxy mode in browser.test_glgears_long. --- tests/test_browser.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_browser.py b/tests/test_browser.py index 57922e9882dd1..aac4a0fa81311 100644 --- a/tests/test_browser.py +++ b/tests/test_browser.py @@ -1344,7 +1344,7 @@ def test_glgears(self): message='You should see animating gears.') def test_glgears_long(self): - for proxy in [0]: + for proxy in [0, 1]: print 'proxy', proxy self.btest('hello_world_gles.c', expected=map(str, range(30, 500)), args=['-DHAVE_BUILTIN_SINCOS', '-DLONGTEST'] + (['--proxy-to-worker'] if proxy else [])) From b3f1a7671dbe10414728fcc2d3137280f66929dc Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Mon, 25 Aug 2014 14:38:09 -0700 Subject: [PATCH 50/60] update other.test_outline for new smaller build sizes --- tests/test_other.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/test_other.py b/tests/test_other.py index 5c2c626d47d19..54da2bfd827c5 100644 --- a/tests/test_other.py +++ b/tests/test_other.py @@ -926,9 +926,9 @@ def measure_funcs(filename): 250: (200, 600), 500: (200, 700), 1000: (230, 1000), - 2000: (300, 2000), + 2000: (250, 2000), 5000: (500, 5000), - 0: (1500, 5000) + 0: (1000, 5000) }), (['-O2'], { 100: (0, 1600), From b62abe1c6bbcaff8875ba4cefb960030d1edd1f9 Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Mon, 25 Aug 2014 14:49:09 -0700 Subject: [PATCH 51/60] text update --- site/build/text/docs/tools_reference/emcc.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/site/build/text/docs/tools_reference/emcc.txt b/site/build/text/docs/tools_reference/emcc.txt index 70626c0c92bfc..332c59c01a606 100644 --- a/site/build/text/docs/tools_reference/emcc.txt +++ b/site/build/text/docs/tools_reference/emcc.txt @@ -208,8 +208,6 @@ Options that are modified or new in *emcc* are listed below: * LLVM LTO is not perfectly stable yet, and can can cause code to behave incorrectly. - . - "--closure " Runs the *Closure Compiler*. Possible "on" values are: From 481371b6d88ea87c43ced7ce308085a0553cf53a Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Mon, 25 Aug 2014 14:55:41 -0700 Subject: [PATCH 52/60] fix old link to wiki --- site/source/docs/packaging/Filesystem-Guide.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/site/source/docs/packaging/Filesystem-Guide.rst b/site/source/docs/packaging/Filesystem-Guide.rst index cf62cb7d722d1..189dc67af9942 100644 --- a/site/source/docs/packaging/Filesystem-Guide.rst +++ b/site/source/docs/packaging/Filesystem-Guide.rst @@ -84,4 +84,5 @@ You can also look at ``FS.readFiles``, which will be an object whose keys are al Manually using the FS API ========================= -Checkout out the `Filesystem API docs `_. +Check out the :ref:`Filesystem-API`. + From 10d481e283edc7b8c7b03d0d17e61c8f921017ff Mon Sep 17 00:00:00 2001 From: Alon Zakai Date: Mon, 25 Aug 2014 15:16:01 -0700 Subject: [PATCH 53/60] deprecate old test modes s_x_x --- tests/runner.py | 2 +- tests/test_core.py | 67 ++++++++++++---------------------------------- 2 files changed, 18 insertions(+), 51 deletions(-) diff --git a/tests/runner.py b/tests/runner.py index 762c10406c7be..7132e69115d22 100755 --- a/tests/runner.py +++ b/tests/runner.py @@ -50,7 +50,7 @@ def nonfastcomp(test): # Core test runner class, shared between normal tests and benchmarks checked_sanity = False -test_modes = ['default', 'asm1', 'asm2', 'asm3', 'asm2f', 'asm2g', 'slow2', 'slow2asm', 's_0_0', 's_0_1'] +test_modes = ['default', 'asm1', 'asm2', 'asm3', 'asm2f', 'asm2g', 'slow2', 'slow2asm'] test_index = 0 class RunnerCore(unittest.TestCase): diff --git a/tests/test_core.py b/tests/test_core.py index ae0424189f060..0f5653e880eea 100644 --- a/tests/test_core.py +++ b/tests/test_core.py @@ -6988,48 +6988,24 @@ def setUp(self): os.chdir(self.get_dir()) # Ensure the directory exists and go there Building.COMPILER = compiler - self.emcc_args = None if emcc_args is None else emcc_args[:] - if self.emcc_args is not None: - Settings.load(self.emcc_args) - Building.LLVM_OPTS = 0 - if '-O2' in self.emcc_args or '-O3' in self.emcc_args: - Building.COMPILER_TEST_OPTS = [] # remove -g in -O2 tests, for more coverage - #Building.COMPILER_TEST_OPTS += self.emcc_args - for arg in self.emcc_args: - if arg.startswith('-O'): - Building.COMPILER_TEST_OPTS.append(arg) # so bitcode is optimized too, this is for cpp to ll - else: - try: - key, value = arg.split('=') - Settings[key] = value # forward -s K=V - except: - pass + assert emcc_args is not None + self.emcc_args = emcc_args[:] + Settings.load(self.emcc_args) + Building.LLVM_OPTS = 0 + if '-O2' in self.emcc_args or '-O3' in self.emcc_args: + Building.COMPILER_TEST_OPTS = [] # remove -g in -O2 tests, for more coverage + #Building.COMPILER_TEST_OPTS += self.emcc_args + for arg in self.emcc_args: + if arg.startswith('-O'): + Building.COMPILER_TEST_OPTS.append(arg) # so bitcode is optimized too, this is for cpp to ll + else: + try: + key, value = arg.split('=') + Settings[key] = value # forward -s K=V + except: + pass return - # TODO: Move much of these to a init() function in shared.py, and reuse that - Settings.ASM_JS = 0 - Settings.USE_TYPED_ARRAYS = typed_arrays - Settings.INVOKE_RUN = 1 - Settings.RELOOP = 0 # we only do them in the "o2" pass - Settings.MICRO_OPTS = embetter - Settings.QUANTUM_SIZE = quantum_size - Settings.ASSERTIONS = 1-embetter - Settings.SAFE_HEAP = 1-embetter - Settings.CHECK_OVERFLOWS = 1-embetter - Settings.CORRECT_OVERFLOWS = 1-embetter - Settings.CORRECT_SIGNS = 0 - Settings.CORRECT_ROUNDINGS = 0 - Settings.CORRECT_OVERFLOWS_LINES = CORRECT_SIGNS_LINES = CORRECT_ROUNDINGS_LINES = SAFE_HEAP_LINES = [] - Settings.CHECK_SIGNS = 0 #1-embetter - Settings.RUNTIME_TYPE_INFO = 0 - Settings.DISABLE_EXCEPTION_CATCHING = 0 - Settings.INCLUDE_FULL_LIBRARY = 0 - Settings.BUILD_AS_SHARED_LIB = 0 - Settings.RUNTIME_LINKED_LIBS = [] - Settings.DOUBLE_MODE = 1 if Settings.USE_TYPED_ARRAYS and Building.LLVM_OPTS == 0 else 0 - Settings.PRECISE_I64_MATH = 0 - Settings.NAMED_GLOBALS = 0 if not embetter else 1 - TT.setUp = setUp return TT @@ -7046,14 +7022,5 @@ def setUp(self): slow2 = make_run("slow2", compiler=CLANG, emcc_args=["-O2", "-s", "ASM_JS=0"], env={"EMCC_FAST_COMPILER": "0"}) slow2asm = make_run("slow2asm", compiler=CLANG, emcc_args=["-O2"], env={"EMCC_FAST_COMPILER": "0"}) -# Legacy test modes - very old -for compiler, quantum, embetter, typed_arrays in [ - (CLANG, 4, 0, 0), - (CLANG, 4, 1, 1), -]: - fullname = 's_0_%d%s%s' % ( - embetter, '' if quantum == 4 else '_q' + str(quantum), '' if typed_arrays in [0, 1] else '_t' + str(typed_arrays) - ) - locals()[fullname] = make_run(fullname, fullname, compiler, embetter, quantum, typed_arrays, env={"EMCC_FAST_COMPILER": "0"}) - del T # T is just a shape for the specific subclasses, we don't test it itself + From 019812094897c07cebb543c5993bbb30df315889 Mon Sep 17 00:00:00 2001 From: hamishwillee Date: Tue, 26 Aug 2014 09:22:45 +1000 Subject: [PATCH 54/60] create new structure for coding guidelins (move some articles, update index) --- .../source/docs/coding/Garbage_Collection.rst | 32 ------------------- .../{ => guidelines}/Asm-pointer-casts.rst | 0 .../{ => guidelines}/Browser-limitations.rst | 0 .../CodeGuidelinesAndLimitations.rst | 0 site/source/docs/coding/guidelines/index.rst | 19 +++++++++++ site/source/docs/coding/index.rst | 5 +-- 6 files changed, 20 insertions(+), 36 deletions(-) delete mode 100644 site/source/docs/coding/Garbage_Collection.rst rename site/source/docs/coding/{ => guidelines}/Asm-pointer-casts.rst (100%) rename site/source/docs/coding/{ => guidelines}/Browser-limitations.rst (100%) rename site/source/docs/coding/{ => guidelines}/CodeGuidelinesAndLimitations.rst (100%) create mode 100644 site/source/docs/coding/guidelines/index.rst diff --git a/site/source/docs/coding/Garbage_Collection.rst b/site/source/docs/coding/Garbage_Collection.rst deleted file mode 100644 index 440cef0893eb1..0000000000000 --- a/site/source/docs/coding/Garbage_Collection.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _GC: - -================================ -Garbage Collection (wiki-import) -================================ -.. note:: This article was migrated from the wiki (Fri, 25 Jul 2014 04:21) and is now the "master copy" (the version in the wiki will be deleted). It may not be a perfect rendering of the original but we hope to fix that soon! - -Emscripten has support for a Boehm-like API for garbage collection in C/C++ programs. This is useful if your application uses the Boehm API or if you are compiling a language like Java into C/C++ with the goal of then translating it to JavaScript. - -API Changes From Boehm ----------------------- - -There is no way to run another thread that interrupts the program at intervals in order to GC. So you need to call ``GC_MAYBE_COLLECT`` at reasonable intervals, which will do a collection if enough allocations happened since the last one. If you compile to HTML, a timer will be spun for this automatically and you don't need to do anything. - -You can also call ``GC_FORCE_COLLECT`` which forces a collection. This is useful if there are times in your app when responsiveness is not important (for example, right before starting a new level in a game). - -Mechanism ---------- - -Static allocations are scanned, but the C and JS stacks are not. We can add such scanning at the cost of runtime performance, however, you don't need stack scanning if you compile for browsers and call ``GC_MAYBE_COLLECT`` from a ``setInterval``, since the interval will run when there is no relevant C or JS stack to scan (as mentioned before, such a timer will be run for you automatically if you are compiling to HTML). - -Pitfalls --------- - -The main risk with the current implementation is that we do not force a collection directly from allocations. So if you allocate a lot in between collections, you can run out of memory. You can call ``GC_FORCE_COLLECT`` to prevent this in some cases if you know relevant parts in your code. - -Relevant Files --------------- - -- ``system/include/gc.h`` -- ``src/library_gc.js`` - diff --git a/site/source/docs/coding/Asm-pointer-casts.rst b/site/source/docs/coding/guidelines/Asm-pointer-casts.rst similarity index 100% rename from site/source/docs/coding/Asm-pointer-casts.rst rename to site/source/docs/coding/guidelines/Asm-pointer-casts.rst diff --git a/site/source/docs/coding/Browser-limitations.rst b/site/source/docs/coding/guidelines/Browser-limitations.rst similarity index 100% rename from site/source/docs/coding/Browser-limitations.rst rename to site/source/docs/coding/guidelines/Browser-limitations.rst diff --git a/site/source/docs/coding/CodeGuidelinesAndLimitations.rst b/site/source/docs/coding/guidelines/CodeGuidelinesAndLimitations.rst similarity index 100% rename from site/source/docs/coding/CodeGuidelinesAndLimitations.rst rename to site/source/docs/coding/guidelines/CodeGuidelinesAndLimitations.rst diff --git a/site/source/docs/coding/guidelines/index.rst b/site/source/docs/coding/guidelines/index.rst new file mode 100644 index 0000000000000..64151d61dbb09 --- /dev/null +++ b/site/source/docs/coding/guidelines/index.rst @@ -0,0 +1,19 @@ +.. _guidelines-index: + +===================================================== +Code Portability and Limitations (under-construction) +===================================================== + +This section is for ..... + + +.. toctree:: + :maxdepth: 1 + + CodeGuidelinesAndLimitations + Asm-pointer-casts + Browser-limitations + + + + diff --git a/site/source/docs/coding/index.rst b/site/source/docs/coding/index.rst index ac57508450505..5970e24fa7dbf 100644 --- a/site/source/docs/coding/index.rst +++ b/site/source/docs/coding/index.rst @@ -11,15 +11,12 @@ This section is for articles explaining the integration points with Emscripten, .. toctree:: :maxdepth: 1 - CodeGuidelinesAndLimitations + guidelines/index Emscripten-browser-environment connecting_cpp_and_javascript/index multimedia_and_graphics/index - Asm-pointer-casts Synchronous-Virtual-XHR-Backed-File-System-Usage debugging/index - Browser-limitations - Garbage_Collection From f037f32421e039fd060a34d2aa429454d8ada156 Mon Sep 17 00:00:00 2001 From: hamishwillee Date: Tue, 26 Aug 2014 09:26:56 +1000 Subject: [PATCH 55/60] rename coding folder to porting --- .../docs/{coding => porting}/Emscripten-browser-environment.rst | 0 .../Synchronous-Virtual-XHR-Backed-File-System-Usage.rst | 0 .../connecting_cpp_and_javascript/Interacting-with-code.rst | 0 .../connecting_cpp_and_javascript/WebIDL-Binder.rst | 0 .../{coding => porting}/connecting_cpp_and_javascript/embind.rst | 0 .../{coding => porting}/connecting_cpp_and_javascript/index.rst | 0 .../using_the_embind_val_class_from_cpp.rst | 0 site/source/docs/{coding => porting}/debugging/Debugging.rst | 0 site/source/docs/{coding => porting}/debugging/index.rst | 0 .../docs/{coding => porting}/guidelines/Asm-pointer-casts.rst | 0 .../docs/{coding => porting}/guidelines/Browser-limitations.rst | 0 .../guidelines/CodeGuidelinesAndLimitations.rst | 0 site/source/docs/{coding => porting}/guidelines/index.rst | 0 site/source/docs/{coding => porting}/index.rst | 0 .../multimedia_and_graphics/EGL-Support-in-Emscripten.rst | 0 .../multimedia_and_graphics/OpenGL-support.rst | 0 .../docs/{coding => porting}/multimedia_and_graphics/index.rst | 0 17 files changed, 0 insertions(+), 0 deletions(-) rename site/source/docs/{coding => porting}/Emscripten-browser-environment.rst (100%) rename site/source/docs/{coding => porting}/Synchronous-Virtual-XHR-Backed-File-System-Usage.rst (100%) rename site/source/docs/{coding => porting}/connecting_cpp_and_javascript/Interacting-with-code.rst (100%) rename site/source/docs/{coding => porting}/connecting_cpp_and_javascript/WebIDL-Binder.rst (100%) rename site/source/docs/{coding => porting}/connecting_cpp_and_javascript/embind.rst (100%) rename site/source/docs/{coding => porting}/connecting_cpp_and_javascript/index.rst (100%) rename site/source/docs/{coding => porting}/connecting_cpp_and_javascript/using_the_embind_val_class_from_cpp.rst (100%) rename site/source/docs/{coding => porting}/debugging/Debugging.rst (100%) rename site/source/docs/{coding => porting}/debugging/index.rst (100%) rename site/source/docs/{coding => porting}/guidelines/Asm-pointer-casts.rst (100%) rename site/source/docs/{coding => porting}/guidelines/Browser-limitations.rst (100%) rename site/source/docs/{coding => porting}/guidelines/CodeGuidelinesAndLimitations.rst (100%) rename site/source/docs/{coding => porting}/guidelines/index.rst (100%) rename site/source/docs/{coding => porting}/index.rst (100%) rename site/source/docs/{coding => porting}/multimedia_and_graphics/EGL-Support-in-Emscripten.rst (100%) rename site/source/docs/{coding => porting}/multimedia_and_graphics/OpenGL-support.rst (100%) rename site/source/docs/{coding => porting}/multimedia_and_graphics/index.rst (100%) diff --git a/site/source/docs/coding/Emscripten-browser-environment.rst b/site/source/docs/porting/Emscripten-browser-environment.rst similarity index 100% rename from site/source/docs/coding/Emscripten-browser-environment.rst rename to site/source/docs/porting/Emscripten-browser-environment.rst diff --git a/site/source/docs/coding/Synchronous-Virtual-XHR-Backed-File-System-Usage.rst b/site/source/docs/porting/Synchronous-Virtual-XHR-Backed-File-System-Usage.rst similarity index 100% rename from site/source/docs/coding/Synchronous-Virtual-XHR-Backed-File-System-Usage.rst rename to site/source/docs/porting/Synchronous-Virtual-XHR-Backed-File-System-Usage.rst diff --git a/site/source/docs/coding/connecting_cpp_and_javascript/Interacting-with-code.rst b/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst similarity index 100% rename from site/source/docs/coding/connecting_cpp_and_javascript/Interacting-with-code.rst rename to site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst diff --git a/site/source/docs/coding/connecting_cpp_and_javascript/WebIDL-Binder.rst b/site/source/docs/porting/connecting_cpp_and_javascript/WebIDL-Binder.rst similarity index 100% rename from site/source/docs/coding/connecting_cpp_and_javascript/WebIDL-Binder.rst rename to site/source/docs/porting/connecting_cpp_and_javascript/WebIDL-Binder.rst diff --git a/site/source/docs/coding/connecting_cpp_and_javascript/embind.rst b/site/source/docs/porting/connecting_cpp_and_javascript/embind.rst similarity index 100% rename from site/source/docs/coding/connecting_cpp_and_javascript/embind.rst rename to site/source/docs/porting/connecting_cpp_and_javascript/embind.rst diff --git a/site/source/docs/coding/connecting_cpp_and_javascript/index.rst b/site/source/docs/porting/connecting_cpp_and_javascript/index.rst similarity index 100% rename from site/source/docs/coding/connecting_cpp_and_javascript/index.rst rename to site/source/docs/porting/connecting_cpp_and_javascript/index.rst diff --git a/site/source/docs/coding/connecting_cpp_and_javascript/using_the_embind_val_class_from_cpp.rst b/site/source/docs/porting/connecting_cpp_and_javascript/using_the_embind_val_class_from_cpp.rst similarity index 100% rename from site/source/docs/coding/connecting_cpp_and_javascript/using_the_embind_val_class_from_cpp.rst rename to site/source/docs/porting/connecting_cpp_and_javascript/using_the_embind_val_class_from_cpp.rst diff --git a/site/source/docs/coding/debugging/Debugging.rst b/site/source/docs/porting/debugging/Debugging.rst similarity index 100% rename from site/source/docs/coding/debugging/Debugging.rst rename to site/source/docs/porting/debugging/Debugging.rst diff --git a/site/source/docs/coding/debugging/index.rst b/site/source/docs/porting/debugging/index.rst similarity index 100% rename from site/source/docs/coding/debugging/index.rst rename to site/source/docs/porting/debugging/index.rst diff --git a/site/source/docs/coding/guidelines/Asm-pointer-casts.rst b/site/source/docs/porting/guidelines/Asm-pointer-casts.rst similarity index 100% rename from site/source/docs/coding/guidelines/Asm-pointer-casts.rst rename to site/source/docs/porting/guidelines/Asm-pointer-casts.rst diff --git a/site/source/docs/coding/guidelines/Browser-limitations.rst b/site/source/docs/porting/guidelines/Browser-limitations.rst similarity index 100% rename from site/source/docs/coding/guidelines/Browser-limitations.rst rename to site/source/docs/porting/guidelines/Browser-limitations.rst diff --git a/site/source/docs/coding/guidelines/CodeGuidelinesAndLimitations.rst b/site/source/docs/porting/guidelines/CodeGuidelinesAndLimitations.rst similarity index 100% rename from site/source/docs/coding/guidelines/CodeGuidelinesAndLimitations.rst rename to site/source/docs/porting/guidelines/CodeGuidelinesAndLimitations.rst diff --git a/site/source/docs/coding/guidelines/index.rst b/site/source/docs/porting/guidelines/index.rst similarity index 100% rename from site/source/docs/coding/guidelines/index.rst rename to site/source/docs/porting/guidelines/index.rst diff --git a/site/source/docs/coding/index.rst b/site/source/docs/porting/index.rst similarity index 100% rename from site/source/docs/coding/index.rst rename to site/source/docs/porting/index.rst diff --git a/site/source/docs/coding/multimedia_and_graphics/EGL-Support-in-Emscripten.rst b/site/source/docs/porting/multimedia_and_graphics/EGL-Support-in-Emscripten.rst similarity index 100% rename from site/source/docs/coding/multimedia_and_graphics/EGL-Support-in-Emscripten.rst rename to site/source/docs/porting/multimedia_and_graphics/EGL-Support-in-Emscripten.rst diff --git a/site/source/docs/coding/multimedia_and_graphics/OpenGL-support.rst b/site/source/docs/porting/multimedia_and_graphics/OpenGL-support.rst similarity index 100% rename from site/source/docs/coding/multimedia_and_graphics/OpenGL-support.rst rename to site/source/docs/porting/multimedia_and_graphics/OpenGL-support.rst diff --git a/site/source/docs/coding/multimedia_and_graphics/index.rst b/site/source/docs/porting/multimedia_and_graphics/index.rst similarity index 100% rename from site/source/docs/coding/multimedia_and_graphics/index.rst rename to site/source/docs/porting/multimedia_and_graphics/index.rst From 856fcff31f5bb96c1f5945b72c5e77c2f871e1c6 Mon Sep 17 00:00:00 2001 From: hamishwillee Date: Tue, 26 Aug 2014 09:36:06 +1000 Subject: [PATCH 56/60] fix up links broken by moving sections --- site/source/docs/index.rst | 2 +- .../docs/porting/guidelines/Asm-pointer-casts.rst | 13 +++++++++++++ .../guidelines/CodeGuidelinesAndLimitations.rst | 12 +----------- site/source/docs/porting/index.rst | 6 +++--- site/source/index.rst | 2 +- 5 files changed, 19 insertions(+), 16 deletions(-) diff --git a/site/source/docs/index.rst b/site/source/docs/index.rst index f3162b2b30a62..100e4937f6781 100644 --- a/site/source/docs/index.rst +++ b/site/source/docs/index.rst @@ -8,7 +8,7 @@ Documentation Home (under-construction) introducing_emscripten/index getting_started/index - coding/index + porting/index optimizing/index compiling/index packaging/index diff --git a/site/source/docs/porting/guidelines/Asm-pointer-casts.rst b/site/source/docs/porting/guidelines/Asm-pointer-casts.rst index f3a0b504baa0e..6436e9c236849 100644 --- a/site/source/docs/porting/guidelines/Asm-pointer-casts.rst +++ b/site/source/docs/porting/guidelines/Asm-pointer-casts.rst @@ -1,3 +1,16 @@ +======================================= +Function Pointer Issues (wiki-import) +======================================= + +There are three general issues with function pointers: + +#. clang generates different code for C and C++ calls when a structure is passed **by value**. The two formats are incompatible in how we generate code in Emscripten, but each is compatible with itself. You should see a warning during compilation about this, and the workaround is to either not mix C and C++ in that location (just renaming a **.c** file to **.cpp** for example) or to pass the structure by reference. (More specifically, one convention is ``struct byval`` and the other is ``field a, field b``.) + +#. In **asm.js** mode, there is an additional concern, with function tables. Without **asm.js**, all function pointers use a single table, but in **asm.js** each function pointer type has its own table (this allows the JavaScript engine to know the exact type of each function pointer call, and optimize those calls much better than normally). As a consequence though, if you have a function that is say ``int (int)`` (return int, receive int) and you cast it to ``void (int)`` (no return, receive int), then the function pointer call will fail because we are looking in the wrong table. This is undefined behavior in C in any case, so it is recommended to refactor code to avoid this type of situation. You should see compilation warnings about these things. See :ref:`Asm-pointer-casts` for more information. + +#. A related issue to do with function pointers is that in ``-O2`` and above we optimize the size of the separate function tables. That means that two functions can have the same function pointer so long as their type is different, and so potentially comparing function pointers of different types can give false positives. Also, it makes bugs with incorrect function pointers potentially more misleading, since there are fewer "holes" in function tables (holes would throw an error instead of running the wrong code). To check if this is causing issues, you can compile with ``-s ALIASING_FUNCTION_POINTERS=0``. + + .. _Asm-pointer-casts: =============================== diff --git a/site/source/docs/porting/guidelines/CodeGuidelinesAndLimitations.rst b/site/source/docs/porting/guidelines/CodeGuidelinesAndLimitations.rst index 3f3e7df672494..01e0341bd7a7c 100644 --- a/site/source/docs/porting/guidelines/CodeGuidelinesAndLimitations.rst +++ b/site/source/docs/porting/guidelines/CodeGuidelinesAndLimitations.rst @@ -1,7 +1,7 @@ .. _CodeGuidelinesAndLimitations: ========================================================= -Code Guidelines and Limitations (under-construction) +Portability Guidelines (under-construction) ========================================================= This article describes the types of code that are more difficult to compile, code which compiles but may run more slowly, and issues and limitations with specific APIs. Developers will find it useful for evaluating the effort to port and re-write code. @@ -50,13 +50,3 @@ Networking - Emscripten supports libc networking functions, but since JavaScript networking is asynchronous, you must limit yourself to asynchronous (nonblocking) operations. -Function pointer issues -======================= - -There are three general issues with function pointers: - -#. clang generates different code for C and C++ calls when a structure is passed **by value**. The two formats are incompatible in how we generate code in Emscripten, but each is compatible with itself. You should see a warning during compilation about this, and the workaround is to either not mix C and C++ in that location (just renaming a **.c** file to **.cpp** for example) or to pass the structure by reference. (More specifically, one convention is ``struct byval`` and the other is ``field a, field b``.) - -#. In **asm.js** mode, there is an additional concern, with function tables. Without **asm.js**, all function pointers use a single table, but in **asm.js** each function pointer type has its own table (this allows the JavaScript engine to know the exact type of each function pointer call, and optimize those calls much better than normally). As a consequence though, if you have a function that is say ``int (int)`` (return int, receive int) and you cast it to ``void (int)`` (no return, receive int), then the function pointer call will fail because we are looking in the wrong table. This is undefined behavior in C in any case, so it is recommended to refactor code to avoid this type of situation. You should see compilation warnings about these things. See :ref:`Asm-pointer-casts` for more information. - -#. A related issue to do with function pointers is that in ``-O2`` and above we optimize the size of the separate function tables. That means that two functions can have the same function pointer so long as their type is different, and so potentially comparing function pointers of different types can give false positives. Also, it makes bugs with incorrect function pointers potentially more misleading, since there are fewer "holes" in function tables (holes would throw an error instead of running the wrong code). To check if this is causing issues, you can compile with ``-s ALIASING_FUNCTION_POINTERS=0``. \ No newline at end of file diff --git a/site/source/docs/porting/index.rst b/site/source/docs/porting/index.rst index 5970e24fa7dbf..eb579b95a1164 100644 --- a/site/source/docs/porting/index.rst +++ b/site/source/docs/porting/index.rst @@ -1,8 +1,8 @@ .. _integrating-porting-index: -================================================== -Integrating/Porting (under-construction) -================================================== +================================ +Porting (under-construction) +================================ This section is for articles explaining the integration points with Emscripten, and general coding guidelines to help you with porting. diff --git a/site/source/index.rst b/site/source/index.rst index 96110efa3769b..1fc261254b10e 100644 --- a/site/source/index.rst +++ b/site/source/index.rst @@ -33,7 +33,7 @@ News docs/introducing_emscripten/index docs/getting_started/index - docs/coding/index + docs/porting/index docs/optimizing/index docs/compiling/index docs/packaging/index From b21418f51437703b67344b5bb98e03eb133a63c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jukka=20Jyl=C3=A4nki?= Date: Tue, 26 Aug 2014 12:12:15 +0300 Subject: [PATCH 57/60] Fix other.test_valid_abspath broken by previous feature to never warn when an absolute path points inside the emscripten tree. --- tests/test_other.py | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/tests/test_other.py b/tests/test_other.py index 54da2bfd827c5..39ba5944f92f2 100644 --- a/tests/test_other.py +++ b/tests/test_other.py @@ -2706,11 +2706,18 @@ def test_bad_triple(self): def test_valid_abspath(self): # Test whether abspath warning appears - abs_include_path = path_from_root('tests') + abs_include_path = os.path.abspath(self.get_dir()) process = Popen([PYTHON, EMCC, '-I%s' % abs_include_path, path_from_root('tests', 'hello_world.c')], stdout=PIPE, stderr=PIPE) out, err = process.communicate() warning = '-I or -L of an absolute path "-I%s" encountered. If this is to a local system header/library, it may cause problems (local system files make sense for compiling natively on your system, but not necessarily to JavaScript). Pass \'-Wno-warn-absolute-paths\' to emcc to hide this warning.' % abs_include_path assert(warning in err) + + # Passing an absolute path to a directory inside the emscripten tree is always ok and should not issue a warning. + abs_include_path = path_from_root('tests') + process = Popen([PYTHON, EMCC, '-I%s' % abs_include_path, path_from_root('tests', 'hello_world.c')], stdout=PIPE, stderr=PIPE) + out, err = process.communicate() + warning = '-I or -L of an absolute path "-I%s" encountered. If this is to a local system header/library, it may cause problems (local system files make sense for compiling natively on your system, but not necessarily to JavaScript). Pass \'-Wno-warn-absolute-paths\' to emcc to hide this warning.' % abs_include_path + assert(warning not in err) # Hide warning for this include path process = Popen([PYTHON, EMCC, '--valid-abspath', abs_include_path,'-I%s' % abs_include_path, path_from_root('tests', 'hello_world.c')], stdout=PIPE, stderr=PIPE) From 87fcddc5f76f46ba1c72456e853f0f498b6dc786 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jukka=20Jyl=C3=A4nki?= Date: Tue, 26 Aug 2014 12:15:32 +0300 Subject: [PATCH 58/60] Make is_valid_abspath use path_from_root() to be more precise about what Emscripten root directory is. --- emcc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/emcc b/emcc index d44314811cdc7..00daef0a794d0 100755 --- a/emcc +++ b/emcc @@ -420,7 +420,7 @@ try: def is_valid_abspath(path_name): # Any path that is underneath the emscripten repository root must be ok. - if '/emscripten/' in path_name.replace('\\', '/'): + if shared.path_from_root().replace('\\', '/') in path_name.replace('\\', '/'): return True for valid_abspath in valid_abspaths: From f104429d587f5237183248b9dc18aaf9d0dc696e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jukka=20Jyl=C3=A4nki?= Date: Tue, 26 Aug 2014 12:36:10 +0300 Subject: [PATCH 59/60] Add test that rand() produces both even and odd numbers (fails). See #2341. --- tests/test_core.py | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/tests/test_core.py b/tests/test_core.py index 0f5653e880eea..de2bf5a8e7d22 100644 --- a/tests/test_core.py +++ b/tests/test_core.py @@ -3767,6 +3767,18 @@ def test_rand(self): for(int i = 0; i < 10; ++i) printf("%d\n", rand_r(&seed)); + bool haveEven = false; + bool haveOdd = false; + for(int i = 0; i < 100; ++i) + { + if ((rand() & 1) == 0) + haveEven = true; + else + haveOdd = true; + } + if (haveEven && haveOdd) + printf("Have even and odd!\n"); + return 0; } ''' @@ -3790,6 +3802,7 @@ def test_rand(self): 1982845871 1210574360 1479617503 +Have even and odd! ''' self.do_run(src, expected) From 4a744fba1a98da15d857b216e92fb1e0b0771e8f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jukka=20Jyl=C3=A4nki?= Date: Tue, 26 Aug 2014 12:38:42 +0300 Subject: [PATCH 60/60] Migrate to musl v1.0.3 prng functions. Fixes #2341. Bump version to 1.23.1 to have cached libc rebuilt with prng routines. --- emscripten-version.txt | 2 +- src/library.js | 27 +--- system/lib/libc.symbols | 21 +++ system/lib/libc/musl/src/prng/__rand48_step.c | 13 ++ system/lib/libc/musl/src/prng/__seed48.c | 1 + system/lib/libc/musl/src/prng/drand48.c | 19 +++ system/lib/libc/musl/src/prng/lcong48.c | 9 ++ system/lib/libc/musl/src/prng/lrand48.c | 15 +++ system/lib/libc/musl/src/prng/mrand48.c | 15 +++ system/lib/libc/musl/src/prng/rand.c | 15 +++ system/lib/libc/musl/src/prng/rand_r.c | 15 +++ system/lib/libc/musl/src/prng/random.c | 122 ++++++++++++++++++ system/lib/libc/musl/src/prng/seed48.c | 12 ++ system/lib/libc/musl/src/prng/srand48.c | 6 + tests/test_core.py | 40 +++--- tools/system_libs.py | 13 ++ 16 files changed, 299 insertions(+), 46 deletions(-) create mode 100644 system/lib/libc/musl/src/prng/__rand48_step.c create mode 100644 system/lib/libc/musl/src/prng/__seed48.c create mode 100644 system/lib/libc/musl/src/prng/drand48.c create mode 100644 system/lib/libc/musl/src/prng/lcong48.c create mode 100644 system/lib/libc/musl/src/prng/lrand48.c create mode 100644 system/lib/libc/musl/src/prng/mrand48.c create mode 100644 system/lib/libc/musl/src/prng/rand.c create mode 100644 system/lib/libc/musl/src/prng/rand_r.c create mode 100644 system/lib/libc/musl/src/prng/random.c create mode 100644 system/lib/libc/musl/src/prng/seed48.c create mode 100644 system/lib/libc/musl/src/prng/srand48.c diff --git a/emscripten-version.txt b/emscripten-version.txt index 5f96aa7b34621..f2c16746929e2 100644 --- a/emscripten-version.txt +++ b/emscripten-version.txt @@ -1,2 +1,2 @@ -1.23.0 +1.23.1 diff --git a/src/library.js b/src/library.js index f31370855522e..a5500bbab4cad 100644 --- a/src/library.js +++ b/src/library.js @@ -3338,31 +3338,6 @@ LibraryManager.library = { return limit; }, - __rand_seed: 'allocate([0x0273459b, 0, 0, 0], "i32", ALLOC_STATIC)', - srand__deps: ['__rand_seed'], - srand: function(seed) { - {{{ makeSetValue('___rand_seed', 0, 'seed', 'i32') }}} - }, - rand_r__sig: 'ii', - rand_r__asm: true, - rand_r: function(seedp) { - seedp = seedp|0; - var val = 0; - val = ((Math_imul({{{ makeGetValueAsm('seedp', 0, 'i32') }}}, 31010991)|0) + 0x676e6177 ) & {{{ cDefine('RAND_MAX') }}}; // assumes RAND_MAX is in bit mask form (power of 2 minus 1) - {{{ makeSetValueAsm('seedp', 0, 'val', 'i32') }}}; - return val|0; - }, - rand__sig: 'i', - rand__asm: true, - rand__deps: ['rand_r', '__rand_seed'], - rand: function() { - return _rand_r(___rand_seed)|0; - }, - - drand48: function() { - return Math.random(); - }, - realpath__deps: ['$FS', '__setErrNo'], realpath: function(file_name, resolved_name) { // char *realpath(const char *restrict file_name, char *restrict resolved_name); @@ -3382,6 +3357,8 @@ LibraryManager.library = { } }, + // For compatibility, call to rand() when code requests arc4random(), although this is *not* at all + // as strong as rc4 is. See https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man3/arc4random.3.html arc4random: 'rand', // ========================================================================== diff --git a/system/lib/libc.symbols b/system/lib/libc.symbols index 8e6dbdb3e5a33..2d1d9db0ca2e4 100644 --- a/system/lib/libc.symbols +++ b/system/lib/libc.symbols @@ -14,6 +14,8 @@ T atol W bulk_free W calloc + T drand48 + T erand48 T ffs W free T frexp @@ -21,9 +23,16 @@ T frexpl W independent_calloc W independent_comalloc + T initstate T isdigit T isspace T isupper + T jrand48 + T lcg31 + T lcg64 + T lcong48 + T loadstate + T lrand48 W mallinfo W malloc W malloc_footprint @@ -36,17 +45,28 @@ W mallopt W memalign T MUSL_vfprintf + T mrand48 + T nrand48 W posix_memalign W pvalloc + T rand + T rand_r + T random W realloc W realloc_in_place T scalbn T scalbnl + T srand T memchr T memcmp T memcpy + T savestate + T seed48 + T setstate T snprintf T sprintf + T srand48 + T srandom T strtod T strtoull T strtoll @@ -63,6 +83,7 @@ T strtof_l T strtold T strtold_l + T temper T tolower W valloc T vsnprintf diff --git a/system/lib/libc/musl/src/prng/__rand48_step.c b/system/lib/libc/musl/src/prng/__rand48_step.c new file mode 100644 index 0000000000000..ccaffc37b199d --- /dev/null +++ b/system/lib/libc/musl/src/prng/__rand48_step.c @@ -0,0 +1,13 @@ +#include + +uint64_t __rand48_step(unsigned short *xi, unsigned short *lc) +{ + uint64_t a, x; + x = xi[0] | xi[1]<<16 | xi[2]+0ULL<<32; + a = lc[0] | lc[1]<<16 | lc[2]+0ULL<<32; + x = a*x + lc[3]; + xi[0] = x; + xi[1] = x>>16; + xi[2] = x>>32; + return x & 0xffffffffffffull; +} diff --git a/system/lib/libc/musl/src/prng/__seed48.c b/system/lib/libc/musl/src/prng/__seed48.c new file mode 100644 index 0000000000000..05a4539e4ee31 --- /dev/null +++ b/system/lib/libc/musl/src/prng/__seed48.c @@ -0,0 +1 @@ +unsigned short __seed48[7] = { 0, 0, 0, 0xe66d, 0xdeec, 0x5, 0xb }; diff --git a/system/lib/libc/musl/src/prng/drand48.c b/system/lib/libc/musl/src/prng/drand48.c new file mode 100644 index 0000000000000..d808353c9872e --- /dev/null +++ b/system/lib/libc/musl/src/prng/drand48.c @@ -0,0 +1,19 @@ +#include +#include + +uint64_t __rand48_step(unsigned short *xi, unsigned short *lc); +extern unsigned short __seed48[7]; + +double erand48(unsigned short s[3]) +{ + union { + uint64_t u; + double f; + } x = { 0x3ff0000000000000ULL | __rand48_step(s, __seed48+3)<<4 }; + return x.f - 1.0; +} + +double drand48(void) +{ + return erand48(__seed48); +} diff --git a/system/lib/libc/musl/src/prng/lcong48.c b/system/lib/libc/musl/src/prng/lcong48.c new file mode 100644 index 0000000000000..32b27d423aa1d --- /dev/null +++ b/system/lib/libc/musl/src/prng/lcong48.c @@ -0,0 +1,9 @@ +#include +#include + +extern unsigned short __seed48[7]; + +void lcong48(unsigned short p[7]) +{ + memcpy(__seed48, p, sizeof __seed48); +} diff --git a/system/lib/libc/musl/src/prng/lrand48.c b/system/lib/libc/musl/src/prng/lrand48.c new file mode 100644 index 0000000000000..a3c4e4e2b2bb0 --- /dev/null +++ b/system/lib/libc/musl/src/prng/lrand48.c @@ -0,0 +1,15 @@ +#include +#include + +uint64_t __rand48_step(unsigned short *xi, unsigned short *lc); +extern unsigned short __seed48[7]; + +long nrand48(unsigned short s[3]) +{ + return __rand48_step(s, __seed48+3) >> 17; +} + +long lrand48(void) +{ + return nrand48(__seed48); +} diff --git a/system/lib/libc/musl/src/prng/mrand48.c b/system/lib/libc/musl/src/prng/mrand48.c new file mode 100644 index 0000000000000..ee650fc3e6a9f --- /dev/null +++ b/system/lib/libc/musl/src/prng/mrand48.c @@ -0,0 +1,15 @@ +#include +#include + +uint64_t __rand48_step(unsigned short *xi, unsigned short *lc); +extern unsigned short __seed48[7]; + +long jrand48(unsigned short s[3]) +{ + return __rand48_step(s, __seed48+3) >> 16; +} + +long mrand48(void) +{ + return jrand48(__seed48); +} diff --git a/system/lib/libc/musl/src/prng/rand.c b/system/lib/libc/musl/src/prng/rand.c new file mode 100644 index 0000000000000..c000cd248cef6 --- /dev/null +++ b/system/lib/libc/musl/src/prng/rand.c @@ -0,0 +1,15 @@ +#include +#include + +static uint64_t seed; + +void srand(unsigned s) +{ + seed = s-1; +} + +int rand(void) +{ + seed = 6364136223846793005ULL*seed + 1; + return seed>>33; +} diff --git a/system/lib/libc/musl/src/prng/rand_r.c b/system/lib/libc/musl/src/prng/rand_r.c new file mode 100644 index 0000000000000..638614c867911 --- /dev/null +++ b/system/lib/libc/musl/src/prng/rand_r.c @@ -0,0 +1,15 @@ +#include + +static unsigned temper(unsigned x) +{ + x ^= x>>11; + x ^= x<<7 & 0x9D2C5680; + x ^= x<<15 & 0xEFC60000; + x ^= x>>18; + return x; +} + +int rand_r(unsigned *seed) +{ + return temper(*seed = *seed * 1103515245 + 12345)/2; +} diff --git a/system/lib/libc/musl/src/prng/random.c b/system/lib/libc/musl/src/prng/random.c new file mode 100644 index 0000000000000..e250e28e98919 --- /dev/null +++ b/system/lib/libc/musl/src/prng/random.c @@ -0,0 +1,122 @@ +#include +#include +#include "libc.h" + +/* +this code uses the same lagged fibonacci generator as the +original bsd random implementation except for the seeding +which was broken in the original +*/ + +static uint32_t init[] = { +0x00000000,0x5851f42d,0xc0b18ccf,0xcbb5f646, +0xc7033129,0x30705b04,0x20fd5db4,0x9a8b7f78, +0x502959d8,0xab894868,0x6c0356a7,0x88cdb7ff, +0xb477d43f,0x70a3a52b,0xa8e4baf1,0xfd8341fc, +0x8ae16fd9,0x742d2f7a,0x0d1f0796,0x76035e09, +0x40f7702c,0x6fa72ca5,0xaaa84157,0x58a0df74, +0xc74a0364,0xae533cc4,0x04185faf,0x6de3b115, +0x0cab8628,0xf043bfa4,0x398150e9,0x37521657}; + +static int n = 31; +static int i = 3; +static int j = 0; +static uint32_t *x = init+1; +static int lock[2]; + +static uint32_t lcg31(uint32_t x) { + return (1103515245*x + 12345) & 0x7fffffff; +} + +static uint64_t lcg64(uint64_t x) { + return 6364136223846793005ull*x + 1; +} + +static void *savestate() { + x[-1] = (n<<16)|(i<<8)|j; + return x-1; +} + +static void loadstate(uint32_t *state) { + x = state+1; + n = x[-1]>>16; + i = (x[-1]>>8)&0xff; + j = x[-1]&0xff; +} + +static void __srandom(unsigned seed) { + int k; + uint64_t s = seed; + + if (n == 0) { + x[0] = s; + return; + } + i = n == 31 || n == 7 ? 3 : 1; + j = 0; + for (k = 0; k < n; k++) { + s = lcg64(s); + x[k] = s>>32; + } + /* make sure x contains at least one odd number */ + x[0] |= 1; +} + +void srandom(unsigned seed) { + LOCK(lock); + __srandom(seed); + UNLOCK(lock); +} + +char *initstate(unsigned seed, char *state, size_t size) { + void *old; + + if (size < 8) + return 0; + LOCK(lock); + old = savestate(); + if (size < 32) + n = 0; + else if (size < 64) + n = 7; + else if (size < 128) + n = 15; + else if (size < 256) + n = 31; + else + n = 63; + x = (uint32_t*)state + 1; + __srandom(seed); + savestate(); + UNLOCK(lock); + return old; +} + +char *setstate(char *state) { + void *old; + + LOCK(lock); + old = savestate(); + loadstate((uint32_t*)state); + UNLOCK(lock); + return old; +} + +long random(void) { + long k; + + LOCK(lock); + if (n == 0) { + k = x[0] = lcg31(x[0]); + goto end; + } + x[i] += x[j]; + k = x[i]>>1; + if (++i == n) + i = 0; + if (++j == n) + j = 0; +end: + UNLOCK(lock); + return k; +} diff --git a/system/lib/libc/musl/src/prng/seed48.c b/system/lib/libc/musl/src/prng/seed48.c new file mode 100644 index 0000000000000..e0699c092afd6 --- /dev/null +++ b/system/lib/libc/musl/src/prng/seed48.c @@ -0,0 +1,12 @@ +#include +#include + +extern unsigned short __seed48[7]; + +unsigned short *seed48(unsigned short *s) +{ + static unsigned short p[3]; + memcpy(p, __seed48, sizeof p); + memcpy(__seed48, s, sizeof p); + return p; +} diff --git a/system/lib/libc/musl/src/prng/srand48.c b/system/lib/libc/musl/src/prng/srand48.c new file mode 100644 index 0000000000000..0a56f6a07a269 --- /dev/null +++ b/system/lib/libc/musl/src/prng/srand48.c @@ -0,0 +1,6 @@ +#include + +void srand48(long seed) +{ + seed48((unsigned short [3]){ 0x330e, seed, seed>>16 }); +} diff --git a/tests/test_core.py b/tests/test_core.py index de2bf5a8e7d22..b343ee88bd959 100644 --- a/tests/test_core.py +++ b/tests/test_core.py @@ -3782,26 +3782,26 @@ def test_rand(self): return 0; } ''' - expected = '''2073540312 -730128159 -1365227432 -1337224527 -792390264 -1952655743 -983994184 -1982845871 -1210574360 -1479617503 -2073540312 -730128159 -1365227432 -1337224527 -792390264 -1952655743 -983994184 -1982845871 -1210574360 -1479617503 + expected = '''490242850 +2074599277 +1480056542 +1912638067 +931112055 +2110392489 +2053422194 +1614832492 +216117595 +174823244 +760368382 +602359081 +1121118963 +1291018924 +1608306807 +352705809 +958258461 +1182561381 +114276303 +1481323674 Have even and odd! ''' self.do_run(src, expected) diff --git a/tools/system_libs.py b/tools/system_libs.py index 51b06fe6499e7..3f35638b27901 100644 --- a/tools/system_libs.py +++ b/tools/system_libs.py @@ -104,6 +104,19 @@ def create_libc(): 'wctomb.c', 'wcrtomb.c', ]], + ['prng', [ + '__rand48_step.c', + '__seed48.c', + 'drand48.c', + 'lcong48.c', + 'lrand48.c', + 'mrand48.c', + 'rand_r.c', + 'rand.c', + 'random.c', + 'seed48.c', + 'srand48.c' + ]], ['stdio', [ '__overflow.c', '__toread.c',