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
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.7, http://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 6.2.0))</title>
<meta name="description" content="Getting Started with Mex-Files (GNU Octave (version 6.2.0))">
<meta name="keywords" content="Getting Started with Mex-Files (GNU Octave (version 6.2.0))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<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">
<link href="Mex_002dFiles.html" rel="prev" title="Mex-Files">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">
</head>
<body lang="en">
<span id="Getting-Started-with-Mex_002dFiles"></span><div class="header">
<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>
<span id="Getting-Started-with-Mex_002dFiles-1"></span><h4 class="subsection">A.2.1 Getting Started with Mex-Files</h4>
<p>The basic command to build a mex-file is either <code>mkoctfile --mex</code> or
<code>mex</code>. The first command can be used either from within Octave or from
the command line. To avoid issues with <small>MATLAB</small>’s own <code>mex</code> command,
the use of the command <code>mex</code> is limited to within Octave. Compiled
mex-files have the extension <samp>.mex</samp>.
</p>
<span id="XREFmex"></span><dl>
<dt id="index-mex-1">: <em></em> <strong>mex</strong> <em>[-options] file …</em></dt>
<dt id="index-mex-2">: <em><code>status</code> =</em> <strong>mex</strong> <em>(…)</em></dt>
<dd><p>Compile source code written in C, C++, or Fortran, to a MEX file.
</p>
<p><var>status</var> is the return status of the <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>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>mkoctfile --mex [-options] file</code>.
</p>
<p><strong>See also:</strong> <a href="Getting-Started-with-Oct_002dFiles.html#XREFmkoctfile">mkoctfile</a>, <a href="#XREFmexext">mexext</a>.
</p></dd></dl>
<span id="XREFmexext"></span><dl>
<dt id="index-mexext">: <em></em> <strong>mexext</strong> <em>()</em></dt>
<dd><p>Return the filename extension used for MEX files.
</p>
<p><strong>See also:</strong> <a href="#XREFmex">mex</a>.
</p></dd></dl>
<p>Consider the following short example:
</p>
<div class="example">
<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>
<p>The first line <code>#include "mex.h"</code> makes available all of the definitions
necessary for a mex-file. One important difference between Octave and
<small>MATLAB</small> is that the header file <code>"matrix.h"</code> is implicitly included
through the inclusion of <code>"mex.h"</code>. This is necessary to avoid a
conflict with the Octave file <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>mexFunction</code>. The
function takes four arguments:
</p>
<ol>
<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>mexFunction</code> and so there can only be a single <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>myhello.c</samp>, it can be compiled with
</p>
<div class="example">
<pre class="example">mkoctfile --mex myhello.c
</pre></div>
<p>which creates a file <samp>myhello.mex</samp>. The function can then be run from
Octave as
</p>
<div class="example">
<pre class="example">myhello (1,2,3)
⇒ Hello, World!
⇒ I have 3 inputs and 0 outputs
</pre></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>myhello.m</samp> which might contain the text
</p>
<div class="example">
<pre class="example">%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>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">
<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>
<p>is in the file <samp>myfunc.c</samp>, and is compiled with
</p>
<div class="example">
<pre class="example">mkoctfile --mex myfunc.c
ln -s myfunc.mex myfunc2.mex
</pre></div>
<p>then as can be seen by
</p>
<div class="example">
<pre class="example">myfunc ()
⇒ You called function: myfunc
This is the principal function
myfunc2 ()
⇒ You called function: myfunc2
</pre></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>mex.h</samp> in their code, Octave
declares additional functions, typedefs, etc., available to the user to write
mex-files in the headers <samp>mexproto.h</samp> and <samp>mxarray.h</samp>.
</p>
<hr>
<div class="header">
<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>
</body>
</html>
|
