152 lines
12 KiB
HTML
152 lines
12 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
||
|
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
||
|
|
<meta name="generator" content="Doxygen 1.8.18"/>
|
||
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
||
|
|
<title>AngelScript: Pre-compiled byte code</title>
|
||
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
||
|
|
<script type="text/javascript" src="jquery.js"></script>
|
||
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
||
|
|
<link href="navtree.css" rel="stylesheet" type="text/css"/>
|
||
|
|
<script type="text/javascript" src="resize.js"></script>
|
||
|
|
<script type="text/javascript" src="navtreedata.js"></script>
|
||
|
|
<script type="text/javascript" src="navtree.js"></script>
|
||
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
||
|
|
<script type="text/javascript" src="search/searchdata.js"></script>
|
||
|
|
<script type="text/javascript" src="search/search.js"></script>
|
||
|
|
<script type="text/javascript">
|
||
|
|
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
||
|
|
$(document).ready(function() { init_search(); });
|
||
|
|
/* @license-end */
|
||
|
|
</script>
|
||
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
||
|
|
<div id="titlearea">
|
||
|
|
<table cellspacing="0" cellpadding="0">
|
||
|
|
<tbody>
|
||
|
|
<tr style="height: 56px;">
|
||
|
|
<td id="projectlogo"><img alt="Logo" src="aslogo_small.png"/></td>
|
||
|
|
<td id="projectalign" style="padding-left: 0.5em;">
|
||
|
|
<div id="projectname">AngelScript
|
||
|
|
</div>
|
||
|
|
</td>
|
||
|
|
<td> <div id="MSearchBox" class="MSearchBoxInactive">
|
||
|
|
<span class="left">
|
||
|
|
<img id="MSearchSelect" src="search/mag_sel.png"
|
||
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
||
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
||
|
|
alt=""/>
|
||
|
|
<input type="text" id="MSearchField" value="Search" accesskey="S"
|
||
|
|
onfocus="searchBox.OnSearchFieldFocus(true)"
|
||
|
|
onblur="searchBox.OnSearchFieldFocus(false)"
|
||
|
|
onkeyup="searchBox.OnSearchFieldChange(event)"/>
|
||
|
|
</span><span class="right">
|
||
|
|
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
|
||
|
|
</span>
|
||
|
|
</div>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</tbody>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
<!-- end header part -->
|
||
|
|
<!-- Generated by Doxygen 1.8.18 -->
|
||
|
|
<script type="text/javascript">
|
||
|
|
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
||
|
|
var searchBox = new SearchBox("searchBox", "search",false,'Search');
|
||
|
|
/* @license-end */
|
||
|
|
</script>
|
||
|
|
</div><!-- top -->
|
||
|
|
<div id="side-nav" class="ui-resizable side-nav-resizable">
|
||
|
|
<div id="nav-tree">
|
||
|
|
<div id="nav-tree-contents">
|
||
|
|
<div id="nav-sync" class="sync"></div>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<div id="splitbar" style="-moz-user-select:none;"
|
||
|
|
class="ui-resizable-handle">
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
<script type="text/javascript">
|
||
|
|
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
||
|
|
$(document).ready(function(){initNavTree('doc_adv_precompile.html',''); initResizable(); });
|
||
|
|
/* @license-end */
|
||
|
|
</script>
|
||
|
|
<div id="doc-content">
|
||
|
|
<!-- window showing the filter options -->
|
||
|
|
<div id="MSearchSelectWindow"
|
||
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
||
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
||
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<!-- iframe showing the search results (closed by default) -->
|
||
|
|
<div id="MSearchResultsWindow">
|
||
|
|
<iframe src="javascript:void(0)" frameborder="0"
|
||
|
|
name="MSearchResults" id="MSearchResults">
|
||
|
|
</iframe>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<div class="PageDoc"><div class="header">
|
||
|
|
<div class="headertitle">
|
||
|
|
<div class="title">Pre-compiled byte code </div> </div>
|
||
|
|
</div><!--header-->
|
||
|
|
<div class="contents">
|
||
|
|
<div class="textblock"><p>Sometimes it may be useful to use pre-compiled bytecode instead of re-building the scripts every time a script is loaded. This can for example reduce load times, or if scripts are transferred over the net, it can reduce the transfer time for large scripts.</p>
|
||
|
|
<p>To save already compiled code you should call the <a class="el" href="classas_i_script_module.html#ac6cd95dd97cc6abf28ab4d82257f5aeb">SaveByteCode</a> method on the <a class="el" href="classas_i_script_module.html">asIScriptModule</a>, passing in a pointer to the object that implements the <a class="el" href="classas_i_binary_stream.html">asIBinaryStream</a> interface. The script module will then push all the bytecode and related data onto this object with the <a class="el" href="classas_i_binary_stream.html#a57724f9cd63a625a843bf97e7704d9a7">Write</a> method.</p>
|
||
|
|
<p>When loading the pre-compiled bytecode you should first get an instance of the <a class="el" href="classas_i_script_module.html">asIScriptModule</a>, just as if compiling a new script. Instead of calling AddScriptSection followed by Build you will call the <a class="el" href="classas_i_script_module.html#a8b4a222e5309c6b367f136b6d2f664ba">LoadByteCode</a> method, passing it a pointer to the binary stream object. The script module will then pull all the bytecode and related data from that object with the <a class="el" href="classas_i_binary_stream.html#a8bbd68cea1f96b42c723f9732ac19140">Read</a> method to reconstruct the script module.</p>
|
||
|
|
<p>Here's a very simple example of how to implement the <a class="el" href="classas_i_binary_stream.html">asIBinaryStream</a> interface:</p>
|
||
|
|
<div class="fragment"><div class="line"><span class="keyword">class </span>CBytecodeStream : <span class="keyword">public</span> <a class="code" href="classas_i_binary_stream.html">asIBinaryStream</a></div>
|
||
|
|
<div class="line">{</div>
|
||
|
|
<div class="line"><span class="keyword">public</span>:</div>
|
||
|
|
<div class="line"> CBytecodeStream(FILE *fp) : f(fp) {}</div>
|
||
|
|
<div class="line"> </div>
|
||
|
|
<div class="line"> <span class="keywordtype">void</span> <a class="code" href="classas_i_binary_stream.html#a57724f9cd63a625a843bf97e7704d9a7">Write</a>(<span class="keyword">const</span> <span class="keywordtype">void</span> *ptr, <a class="code" href="angelscript_8h.html#ac8186f029686800b7ce36bde4a55c815">asUINT</a> size) </div>
|
||
|
|
<div class="line"> {</div>
|
||
|
|
<div class="line"> <span class="keywordflow">if</span>( size == 0 ) <span class="keywordflow">return</span>; </div>
|
||
|
|
<div class="line"> fwrite(ptr, size, 1, f); </div>
|
||
|
|
<div class="line"> }</div>
|
||
|
|
<div class="line"> <span class="keywordtype">void</span> <a class="code" href="classas_i_binary_stream.html#a8bbd68cea1f96b42c723f9732ac19140">Read</a>(<span class="keywordtype">void</span> *ptr, <a class="code" href="angelscript_8h.html#ac8186f029686800b7ce36bde4a55c815">asUINT</a> size) </div>
|
||
|
|
<div class="line"> { </div>
|
||
|
|
<div class="line"> <span class="keywordflow">if</span>( size == 0 ) <span class="keywordflow">return</span>; </div>
|
||
|
|
<div class="line"> fread(ptr, size, 1, f); </div>
|
||
|
|
<div class="line"> }</div>
|
||
|
|
<div class="line"> </div>
|
||
|
|
<div class="line"><span class="keyword">protected</span>:</div>
|
||
|
|
<div class="line"> FILE *f;</div>
|
||
|
|
<div class="line">};</div>
|
||
|
|
</div><!-- fragment --><dl class="section see"><dt>See also</dt><dd><a class="el" href="doc_samples_asbuild.html">Generic compiler</a></dd></dl>
|
||
|
|
<h1><a class="anchor" id="doc_adv_precompile_1"></a>
|
||
|
|
Things to remember</h1>
|
||
|
|
<ul>
|
||
|
|
<li>All the objects, methods, properties, etc, used when compiling the bytecode must also be registered when loading the precompiled bytecode, otherwise the load will fail when not finding the correct entity.</li>
|
||
|
|
<li>The script engine doesn't perform validation of the pre-compiled bytecode, so the application is responsible for authenticating the source. If this authentication isn't performed by the application you'll have potential security risks in your application as the bytecode may have been manually manipulated to perform otherwise illegal tasks.</li>
|
||
|
|
<li>If the application that compiles the script code is separate from the application that will execute them, then you may register the functions and methods with null pointers so you don't need to actually implement all of them. Object properties must be registered with different offsets so that they can be differentiated by the bytecode loader. You should also set the engine property <a class="el" href="angelscript_8h.html#a53c2e8a74ade77c928316396394ebe0facac241d97facce4eaf9e5b0ca40dfcf1">asEP_INIT_GLOBAL_VARS_AFTER_BUILD</a> to false with <a class="el" href="classas_i_script_engine.html#a1bce4e5f573a2ca0ff55163e28f761dd">asIScriptEngine::SetEngineProperty</a>, so the script engine doesn't attempt to initialize the global variables after the script has been built. The <a class="el" href="doc_addon_helpers.html">helper add-on</a> has a couple of functions to facilitate building an offline compiler.</li>
|
||
|
|
<li>If the application is not going to compile scripts from source code, but only load pre-compiled scripts, then it may be beneficial to compile the library with the AS_NO_COMPILER define so as to reduce the size of the executable.</li>
|
||
|
|
<li>To reduce the size of the saved bytecode you can strip the debug information from the code. This will skip saving information that is not necessary for executing the scripts, such as the name of script sections, line numbers, and the name and type of local variables.</li>
|
||
|
|
<li>If the scripts use <a class="el" href="doc_script_shared.html">shared entities</a> then the size of the saved bytecode can be further reduced if the entities are declared as <a class="el" href="doc_script_shared.html#doc_script_shared_external">external</a>. To allow the offline compiler to compile scripts with external shared entities, the offline compiler must first build another module with all the shared entities that should be allowed to be declared as external.</li>
|
||
|
|
<li>The saved bytecode is platform independent with only a couple of exceptions that is unlikely to affect application developers. The exceptions are 1) difference in size of primitive types (e.g. bool on older Mac PPC platforms) and 2) CPU floating point representation (i.e. IEEE 754 versus non-IEEE 754). Differences in pointer size (32bit vs 64bit), CPU endianess, different size of registered types and offsets of registered properties are all handled to provide platform independence.</li>
|
||
|
|
<li>The saved bytecode is not guaranteed to be compatible for different versions of the AngelScript library so make sure you use the same library version when saving the bytecode that will be used when loading it. </li>
|
||
|
|
</ul>
|
||
|
|
</div></div><!-- contents -->
|
||
|
|
</div><!-- PageDoc -->
|
||
|
|
</div><!-- doc-content -->
|
||
|
|
<div class="ttc" id="aclassas_i_binary_stream_html_a8bbd68cea1f96b42c723f9732ac19140"><div class="ttname"><a href="classas_i_binary_stream.html#a8bbd68cea1f96b42c723f9732ac19140">asIBinaryStream::Read</a></div><div class="ttdeci">virtual int Read(void *ptr, asUINT size)=0</div><div class="ttdoc">Read size bytes from the stream into the memory pointed to by ptr.</div></div>
|
||
|
|
<div class="ttc" id="aangelscript_8h_html_ac8186f029686800b7ce36bde4a55c815"><div class="ttname"><a href="angelscript_8h.html#ac8186f029686800b7ce36bde4a55c815">asUINT</a></div><div class="ttdeci">unsigned int asUINT</div><div class="ttdoc">32 bit unsigned integer</div><div class="ttdef"><b>Definition:</b> angelscript.h:600</div></div>
|
||
|
|
<div class="ttc" id="aclassas_i_binary_stream_html"><div class="ttname"><a href="classas_i_binary_stream.html">asIBinaryStream</a></div><div class="ttdoc">A binary stream interface.</div><div class="ttdef"><b>Definition:</b> angelscript.h:4051</div></div>
|
||
|
|
<div class="ttc" id="aclassas_i_binary_stream_html_a57724f9cd63a625a843bf97e7704d9a7"><div class="ttname"><a href="classas_i_binary_stream.html#a57724f9cd63a625a843bf97e7704d9a7">asIBinaryStream::Write</a></div><div class="ttdeci">virtual int Write(const void *ptr, asUINT size)=0</div><div class="ttdoc">Write size bytes to the stream from the memory pointed to by ptr.</div></div>
|
||
|
|
<!-- start footer part -->
|
||
|
|
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
||
|
|
<ul>
|
||
|
|
<li class="footer">Generated on Sat Dec 5 2020 23:20:24 for AngelScript by
|
||
|
|
<a href="http://www.doxygen.org/index.html">
|
||
|
|
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.18 </li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
</body>
|
||
|
|
</html>
|