230 lines
18 KiB
HTML
230 lines
18 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: Compile the library</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_compile_lib.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">Compile the library </div> </div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><p>In the sdk/angelscript/projects directory you'll find project files for many of the popular compilers. However, these project files are not always up to date with the latest version of the library. If you get any compiler or linker errors please make sure the project file include all the files in the sdk/angelscript/source directory, and that the project settings are set according to this article.</p>
|
|
<p>If you don't find a project file for your compiler, you can easily create your own project by adding all the files in the sdk/angelscript/source directory, and configuring the project apropriately. If you have a new compiler/target that hasn't been used with AngelScript before, you may need to edit the as_config.h file to make sure the library is compiled properly.</p>
|
|
<dl class="section see"><dt>See also</dt><dd><a class="el" href="doc_compile_lib.html#doc_compile_platforms">Considerations for specific platforms</a></dd></dl>
|
|
<h1><a class="anchor" id="doc_compile_lib_1"></a>
|
|
Set compile time options</h1>
|
|
<p>The code tries to contain compiler differences in as few places as possible. The header as_config.h was created for that purpose. There you will find some #defines that allow different compilers to work. You'll probably not have to change this file, but if you're using a compiler not previously used and you're getting compiler errors it might be worth it to take a look at this file.</p>
|
|
<p>There are also a couple of other #defines used in the code to alter the compilation. When compiling the library you might want to define ANGELSCRIPT_EXPORT so that library functions are exported. If you include the library source code directly in your application project you shouldn't have to define this flag.</p>
|
|
<p>If AS_DEPRECATED is defined then some backwards compatibility is maintained, this can help you do the upgrade to the latest version a little more smoothly. There is no guarantee that the backwards compatibility will be maintained though so try to remove use of deprecated functions as soon as possible.</p>
|
|
<h1><a class="anchor" id="doc_compile_lib_2"></a>
|
|
Linking with the library</h1>
|
|
<p>There are four ways of compiling and linking with AngelScript in order to use it. I recommend linking with a static library. Note that all four ways are interchangable with only a small change in your code, i.e a defined flag before including the header file, and possibly a routine for manually loading the dll. The rest of your code should look exactly the same for each of the alternatives.</p>
|
|
<h2><a class="anchor" id="doc_compile_lib_2_1"></a>
|
|
1. Include library source files in project</h2>
|
|
<p>You can take the source files for AngelScript and include them directly in your own project. The advantage of this is that you can be sure that the same compiler options are used for the library and the host applications, e.g. multi-threaded or single-threaded CRT. The disadvantage is that your project will be poluted with the library files.</p>
|
|
<p>The files that need to use the library should include the angelscript.h header with no need for any special settings.</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// Include the library interface</span></div>
|
|
<div class="line"><span class="preprocessor">#include "<a class="code" href="angelscript_8h.html">angelscript.h</a>"</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// ... Start using the library</span></div>
|
|
</div><!-- fragment --><h2><a class="anchor" id="doc_compile_lib_2_2"></a>
|
|
2. Compile a static library and link into project</h2>
|
|
<p>The most recommended way is to compile a static library that your project will link with. When compiling the static library you have to make sure that the correct compiler settings are used so that you don't get conflicts in linkage with the CRT functions. This happens if you for example compile the library with dynamically linked multi-threaded CRT and your application with statically linked single-threaded CRT. (For Visual C++ you'll find these settings under Project -> Settings -> C/C++ -> Category: Code Generation)</p>
|
|
<p>To use the library you only need to include the angelscript.h header file.</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// Include the library interface</span></div>
|
|
<div class="line"><span class="preprocessor">#include "<a class="code" href="angelscript_8h.html">angelscript.h</a>"</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// ... Start using the library</span></div>
|
|
</div><!-- fragment --><h2><a class="anchor" id="doc_compile_lib_2_3"></a>
|
|
3. Compile a dynamically loaded library with an import library</h2>
|
|
<p>With Microsoft Visual C++ it is possible to compile a dynamically loaded library with an import library. The import library will then take care of the work needed to load the dll and bind the functions. A possible disadvantage of this method is that you are not able to give any user-friendly error messages in case loading the library fails.</p>
|
|
<p>To use the library you'll have to define ANGELSCRIPT_DLL_LIBRARY_IMPORT before including the angelscript.h header file.</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// Include the library interface</span></div>
|
|
<div class="line"><span class="preprocessor">#define ANGELSCRIPT_DLL_LIBRARY_IMPORT</span></div>
|
|
<div class="line"><span class="preprocessor">#include "<a class="code" href="angelscript_8h.html">angelscript.h</a>"</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// ... Start using the library</span></div>
|
|
</div><!-- fragment --><h2><a class="anchor" id="doc_compile_lib_2_4"></a>
|
|
4. Load the dynamically loaded library manually</h2>
|
|
<p>If you want to use a dll, e.g. to share code between applications, I recommend loading the library manually as you can treat any failures to load or bind functions graciously.</p>
|
|
<p>To use manually loaded dll, you should define ANGELSCRIPT_DLL_MANUAL_IMPORT before including the angelscript.h header file. This will insure that the header file doesn't declare the function prototypes, as you will most likely want to use these names for the function pointers.</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// Include the library interface</span></div>
|
|
<div class="line"><span class="preprocessor">#define ANGELSCRIPT_DLL_MANUAL_IMPORT</span></div>
|
|
<div class="line"><span class="preprocessor">#include "<a class="code" href="angelscript_8h.html">angelscript.h</a>"</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// Declare the function pointers</span></div>
|
|
<div class="line"><span class="keyword">typedef</span> <a class="code" href="classas_i_script_engine.html">asIScriptEngine</a> * AS_CALL t_asCreateScriptEngine(<span class="keywordtype">int</span>);</div>
|
|
<div class="line">t_asCreateScriptEngine *<a class="code" href="group__api__principal__functions.html#gacb6a62345d9cca6c9b5a3dac67d80d0b">asCreateScriptEngine</a> = 0;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// ... Declare the rest of the functions</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// Load the dll and bind the functions (error handling left out for clarity)</span></div>
|
|
<div class="line">HMODULE dll = LoadLibrary(<span class="stringliteral">"angelscript.dll"</span>);</div>
|
|
<div class="line"><a class="code" href="group__api__principal__functions.html#gacb6a62345d9cca6c9b5a3dac67d80d0b">asCreateScriptEngine</a> = (t_asCreateScriptEngine*)GetProcAddress(dll, <span class="stringliteral">"_asCreateScriptEngine"</span>);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// ... Bind the other functions</span></div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// ... Start using the library</span></div>
|
|
</div><!-- fragment --><h1><a class="anchor" id="doc_compile_platforms"></a>
|
|
Considerations for specific platforms</h1>
|
|
<p>As mentioned before, for most platforms the compilation of the library is as easy as including all source files and compiling them. However, on some platforms specific actions needs to be performed to compile the library correctly.</p>
|
|
<h2><a class="anchor" id="doc_compile_win64"></a>
|
|
Windows 64bit</h2>
|
|
<p>The MSVC compiler doesn't support inline assembler for the x86 64bit CPU family. To support this platform a separate assembler file has been created: as_callfunc_x64_msvc_asm.asm.</p>
|
|
<p>To compile this file it is necessary to configure a custom build command with the following:</p>
|
|
<div class="fragment"><div class="line">ml64.exe /c /nologo /Fo$(OutDir)\as_callfunc_x64_msvc_asm.obj /W3 /Zi /Ta $(InputDir)\$(InputFileName)</div>
|
|
</div><!-- fragment --><h2><a class="anchor" id="doc_compile_msvc_sdk"></a>
|
|
Microsoft Visual C++</h2>
|
|
<p>While AngelScript doesn't use Microsoft's language extensions you may still face trouble compiling the library if you disable the language extensions. This is because Microsoft's own SDK may have code that relies on the language extensions, e.g. in version 6.0a you might get compiler errors due to the existance of $ in the macro definitions in the specstrings.h header from the Platform SDK. This particular problem was fixed by Microsoft in version 6.1 of their SDK, but there may be others so it might just easier to leave the language extensions turned on.</p>
|
|
<h2><a class="anchor" id="doc_compile_gnuc"></a>
|
|
GNUC based compilers</h2>
|
|
<p>In order to properly intergrate with C++ without the need for wrappers AngelScript uses a lot of pointer casts. Unfortunately it is not possible to always guarantee strict aliasing because of this, so on GNUC based compilers it is necessary to disable compiler optimizations that assume strict aliasing.</p>
|
|
<p>Use the following compiler argument to disable this:</p>
|
|
<div class="fragment"><div class="line">-fno-strict-aliasing</div>
|
|
</div><!-- fragment --><h2><a class="anchor" id="doc_compile_pocketpc"></a>
|
|
Pocket PC with ARM CPU</h2>
|
|
<p>The MSVC compiler doesn't support inline assembler for the ARM CPU, so a separate assembler file has been written with this code: as_callfunc_arm_msvc.asm.</p>
|
|
<p>In order to compile this file properly it is necessary to configure a custom build command with the following:</p>
|
|
<div class="fragment"><div class="line">armasm -g $(InputPath)</div>
|
|
</div><!-- fragment --><h2><a class="anchor" id="doc_compile_marmalade"></a>
|
|
Marmalade</h2>
|
|
<p>Marmalade is a cross platform SDK created with mobile devices in mind. It functions by abstracting the underlying OS with its own C runtime library even though it uses the common C++ compilers, e.g. MSVC on Windows, and GNUC on Linux and Mac.</p>
|
|
<p>When compiling AngelScript with Marmalade for iOS and Android scons must be used in order to properly compile the native ARM assembler routines. For Windows Phone you should be able to use MSVC normally.</p>
|
|
<h1><a class="anchor" id="doc_compile_size"></a>
|
|
Size of the library</h1>
|
|
<p>The size of the library depends on many different factors, such as compiler brand, compiler flags, and also what features of AngelScript that are included. However, to give an idea of how much space the library will take up on the disk and memory I've compiled the <a class="el" href="doc_samples_asrun.html">asrun sample</a> in a few different ways and noted down the size.</p>
|
|
<table class="doxtable">
|
|
<tr>
|
|
<td><b>Options</b></td><td><b>Size of binary on disk</b> </td></tr>
|
|
<tr>
|
|
<td>32 bit / multithreaded dll / optimize for speed<br />
|
|
Without including AngelScript</td><td>14KB </td></tr>
|
|
<tr>
|
|
<td>32 bit / multithreaded dll / optimize for speed<br />
|
|
Using AngelScript and add-ons</td><td>796KB </td></tr>
|
|
<tr>
|
|
<td>32 bit / multithreaded dll / optimize for speed<br />
|
|
AngelScript without compiler (AS_NO_COMPILER) and add-ons</td><td>453KB </td></tr>
|
|
<tr>
|
|
<td>32 bit / multithreaded static / optimize for speed<br />
|
|
Using AngelScript but without add-ons</td><td>867KB </td></tr>
|
|
<tr>
|
|
<td>32 bit / multithreaded static / optimize for speed<br />
|
|
Using AngelScript and add-ons</td><td>1015KB </td></tr>
|
|
<tr>
|
|
<td>64 bit / multithreaded static / optimize for speed<br />
|
|
Using AngelScript and add-ons</td><td>1336KB </td></tr>
|
|
<tr>
|
|
<td>32 bit / multithreaded static / optimize for size<br />
|
|
Using AngelScript and add-ons</td><td>797KB </td></tr>
|
|
<tr>
|
|
<td>32 bit / multithreaded dll / optimize for size<br />
|
|
Using AngelScript and add-ons</td><td>582KB </td></tr>
|
|
</table>
|
|
<p>Based on this we can draw the conclusion that the engine and VM takes up about 300KB when optimized for speed, the compiler adds another 350KB, and the add-ons yet another 150KB.</p>
|
|
<dl class="section note"><dt>Note</dt><dd>These tests were made with MSVC 2012 and version 2.30.2 of the library. </dd></dl>
|
|
</div></div><!-- contents -->
|
|
</div><!-- PageDoc -->
|
|
</div><!-- doc-content -->
|
|
<div class="ttc" id="aclassas_i_script_engine_html"><div class="ttname"><a href="classas_i_script_engine.html">asIScriptEngine</a></div><div class="ttdoc">The engine interface.</div><div class="ttdef"><b>Definition:</b> angelscript.h:1092</div></div>
|
|
<div class="ttc" id="agroup__api__principal__functions_html_gacb6a62345d9cca6c9b5a3dac67d80d0b"><div class="ttname"><a href="group__api__principal__functions.html#gacb6a62345d9cca6c9b5a3dac67d80d0b">asCreateScriptEngine</a></div><div class="ttdeci">AS_API asIScriptEngine * asCreateScriptEngine(asDWORD version=ANGELSCRIPT_VERSION)</div><div class="ttdoc">Creates the script engine.</div></div>
|
|
<div class="ttc" id="aangelscript_8h_html"><div class="ttname"><a href="angelscript_8h.html">angelscript.h</a></div><div class="ttdoc">The API definition for AngelScript.</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>
|