1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Getting Started with Mex-Files (GNU Octave (version 10.3.0))</title>
<meta name="description" content="Getting Started with Mex-Files (GNU Octave (version 10.3.0))">
<meta name="keywords" content="Getting Started with Mex-Files (GNU Octave (version 10.3.0))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Concept-Index.html" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Mex_002dFiles.html" rel="up" title="Mex-Files">
<link href="Working-with-Matrices-and-Arrays-in-Mex_002dFiles.html" rel="next" title="Working with Matrices and Arrays in Mex-Files">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
div.example {margin-left: 3.2em}
span:hover a.copiable-link {visibility: visible}
strong.def-name {font-family: monospace; font-weight: bold; font-size: larger}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">
</head>
<body lang="en">
<div class="subsection-level-extent" id="Getting-Started-with-Mex_002dFiles">
<div class="nav-panel">
<p>
Next: <a href="Working-with-Matrices-and-Arrays-in-Mex_002dFiles.html" accesskey="n" rel="next">Working with Matrices and Arrays in Mex-Files</a>, Up: <a href="Mex_002dFiles.html" accesskey="u" rel="up">Mex-Files</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h4 class="subsection" id="Getting-Started-with-Mex_002dFiles-1"><span>A.2.1 Getting Started with Mex-Files<a class="copiable-link" href="#Getting-Started-with-Mex_002dFiles-1"> ¶</a></span></h4>
<p>The basic command to build a mex-file is either <code class="code">mkoctfile --mex</code> or
<code class="code">mex</code>. The first command can be used either from within Octave or from
the command line. To avoid issues with <small class="sc">MATLAB</small>’s own <code class="code">mex</code> command,
the use of the command <code class="code">mex</code> is limited to within Octave. Compiled
mex-files have the extension <samp class="file">.mex</samp>.
</p>
<a class="anchor" id="XREFmex"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-mex-1"><span><strong class="def-name">mex</strong> <code class="def-code-arguments">[-options] file …</code><a class="copiable-link" href="#index-mex-1"> ¶</a></span></dt>
<dt class="deftypefnx def-cmd-deftypefn" id="index-mex-2"><span><code class="def-type"><code class="code">status</code> =</code> <strong class="def-name">mex</strong> <code class="def-code-arguments">(…)</code><a class="copiable-link" href="#index-mex-2"> ¶</a></span></dt>
<dd><p>Compile source code written in C, C++, or Fortran, to a MEX file.
</p>
<p><var class="var">status</var> is the return status of the <code class="code">mkoctfile</code> function.
</p>
<p>If the compilation fails, and the output argument is not requested,
an error is raised. If the programmer requests <var class="var">status</var>, however,
Octave will merely issue a warning and it is the programmer’s responsibility
to verify the command was successful.
</p>
<p>This is equivalent to <code class="code">mkoctfile --mex [-options] file</code>.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="Getting-Started-with-Oct_002dFiles.html#XREFmkoctfile">mkoctfile</a>, <a class="ref" href="#XREFmexext">mexext</a>.
</p></dd></dl>
<a class="anchor" id="XREFmexext"></a><span style="display:block; margin-top:-4.5ex;"> </span>
<dl class="first-deftypefn">
<dt class="deftypefn" id="index-mexext"><span><code class="def-type"><var class="var">ext</var> =</code> <strong class="def-name">mexext</strong> <code class="def-code-arguments">()</code><a class="copiable-link" href="#index-mexext"> ¶</a></span></dt>
<dd><p>Return the filename extension used for MEX files.
</p>
<p>Programming Note: Octave uses the extension <samp class="file">mex</samp> for all MEX files
regardless of the operating system (Linux, Windows, Apple) or the bit-width
(32-bit or 64-bit) of the hardware.
</p>
<p><strong class="strong">See also:</strong> <a class="ref" href="#XREFmex">mex</a>.
</p></dd></dl>
<p>Consider the following short example:
</p>
<div class="example">
<div class="group"><pre class="verbatim">#include "mex.h"
void
mexFunction (int nlhs, mxArray *plhs[],
int nrhs, const mxArray *prhs[])
{
mexPrintf ("Hello, World!\n");
mexPrintf ("I have %d inputs and %d outputs\n", nrhs, nlhs);
/* Return empty matrices for any outputs */
int i;
for (i = 0; i < nlhs; i++)
plhs[i] = mxCreateDoubleMatrix (0, 0, mxREAL);
}
</pre></div></div>
<p>The first line <code class="code">#include "mex.h"</code> makes available all of the definitions
necessary for a mex-file. One important difference between Octave and
<small class="sc">MATLAB</small> is that the header file <code class="code">"matrix.h"</code> is implicitly included
through the inclusion of <code class="code">"mex.h"</code>. This is necessary to avoid a
conflict with the Octave file <code class="code">"Matrix.h"</code> for operating systems and
compilers that don’t distinguish between filenames in upper and lower case.
</p>
<p>The entry point into the mex-file is defined by <code class="code">mexFunction</code>. The
function takes four arguments:
</p>
<ol class="enumerate">
<li> The number of return arguments (# of left-hand side args).
</li><li> An array of pointers to return arguments.
</li><li> The number of input arguments (# of right-hand side args).
</li><li> An array of pointers to input arguments.
</li></ol>
<p>Note that the function name definition is not explicitly included in
<code class="code">mexFunction</code> and so there can only be a single <code class="code">mexFunction</code> entry
point per file. Instead, the name of the function as seen in Octave is
determined by the name of the mex-file itself minus the extension. If the
above function is in the file <samp class="file">myhello.c</samp>, it can be compiled with
</p>
<div class="example">
<pre class="example-preformatted">mkoctfile --mex myhello.c
</pre></div>
<p>which creates a file <samp class="file">myhello.mex</samp>. The function can then be run from
Octave as
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">myhello (1,2,3)
⇒ Hello, World!
⇒ I have 3 inputs and 0 outputs
</pre></div></div>
<p>It should be noted that the mex-file contains no help string. To document
mex-files, there should exist an m-file in the same directory as the mex-file
itself. Taking the above as an example, there would need to be a file
<samp class="file">myhello.m</samp> which might contain the text
</p>
<div class="example">
<pre class="example-preformatted">%MYHELLO Simple test of the functionality of a mex-file.
</pre></div>
<p>In this case, the function that will be executed within Octave will be given by
the mex-file, while the help string will come from the m-file. This can also
be useful to allow a sample implementation of the mex-file within the Octave
language itself for testing purposes.
</p>
<p>Although there cannot be multiple entry points in a single mex-file, one can
use the <code class="code">mexFunctionName</code> function to determine what name the mex-file was
called with. This can be used to alter the behavior of the mex-file based on
the function name. For example, if
</p>
<div class="example">
<div class="group"><pre class="verbatim">#include "mex.h"
void
mexFunction (int nlhs, mxArray *plhs[],
int nrhs, const mxArray *prhs[])
{
const char *nm;
nm = mexFunctionName ();
mexPrintf ("You called function: %s\n", nm);
if (strcmp (nm, "myfunc") == 0)
mexPrintf ("This is the principal function\n", nm);
return;
}
</pre></div></div>
<p>is in the file <samp class="file">myfunc.c</samp>, and is compiled with
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">mkoctfile --mex myfunc.c
ln -s myfunc.mex myfunc2.mex
</pre></div></div>
<p>then as can be seen by
</p>
<div class="example">
<div class="group"><pre class="example-preformatted">myfunc ()
⇒ You called function: myfunc
This is the principal function
myfunc2 ()
⇒ You called function: myfunc2
</pre></div></div>
<p>the behavior of the mex-file can be altered depending on the function’s name.
</p>
<p>Although the user should only include <samp class="file">mex.h</samp> in their code, Octave
declares additional functions, typedefs, etc., available to the user to write
mex-files in the headers <samp class="file">mexproto.h</samp> and <samp class="file">mxarray.h</samp>.
</p>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Working-with-Matrices-and-Arrays-in-Mex_002dFiles.html">Working with Matrices and Arrays in Mex-Files</a>, Up: <a href="Mex_002dFiles.html">Mex-Files</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
