lib/w64devkit
1
0
Fork 0
mirror of https://github.com/skeeto/w64devkit.git synced 2026-10-23 06:08:56 +03:00
Code Activity

Add manual pages for ninja, makensis, widl, gendef and cmcldeps

Browse Source 
None of them installs a page of its own, so each was written from its
source and checked by running the kit's build. With these, every program
in bin/ has a page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Christopher Wellons
2026-10-20 07:42:26 -04:00
parent 880be39a58
commit 1e7471f7d0
6 changed files with 3597 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
man/README.md
View File

@@ -1,9 +1,10 @@
# Manual pages
Hand-written manual pages for commands in w64devkit that have no upstream
page: the kit's own tools in `src/`, and the busybox applets. The tree
mirrors `share/man`, and the Dockerfile copies each `manN/` directory into
`$PREFIX/share/man/`. This file does not ship.
page: the kit's own tools in `src/`, the busybox applets, and others such
as `ninja` and `gendef`. The tree mirrors `share/man`, and the Dockerfile
copies each `manN/` directory into `$PREFIX/share/man/`. This file does
not ship.
Pages are man(7) source, formatted in the kit by `nroff`, the kit's own
formatter (`nroff.1`), and displayed by busybox `man` through `less -R`.
@@ -200,11 +201,3 @@ mandoc in Docker:
groff -man -Tutf8 -rLL=78n -rLT=78n -P-cbou xxd.1'
`man` passes `-rLL=78n` on an 80-column terminal.
## Pages still missing
* `ninja`: no upstream page.
* `makensis`: no upstream page.
* `gendef`: no upstream page.
* `widl`: adapt Wine's `tools/widl/widl.man.in` at wine-11.5 (LGPL).
* `cmcldeps`: no upstream page.

263
man/man1/cmcldeps.1 Normal file
View File

@@ -0,0 +1,263 @@
.TH CMCLDEPS 1 2026-10-20 "w64devkit" "w64devkit Manual"
.SH NAME
cmcldeps \- run rc and record the headers a resource script includes
.SH SYNOPSIS
.B cmcldeps RC
.I source depfile object prefix cl rc
.RI [ argument ...]
.SH DESCRIPTION
.B cmcldeps
is an internal helper of
.BR cmake (1).
When CMake's Ninja generator compiles a resource script with Microsoft
.B rc
on a Windows host, as it does for MSVC and compilers that imitate it, the
build rule runs the
.B rc
command through
.B cmcldeps
so that Ninja learns which headers the script includes.
.B rc
cannot list them, so
.B cmcldeps
preprocesses the script with the MSVC compiler
.I cl
to find them, in three steps:
.IP 1. 4
Run
.I cl
with
.B "/P /DRC_INVOKED /nologo /showIncludes /TC"
followed by the
.I argument
list, in the directory part of
.IR object ,
up to its last backslash, or in the current directory if it has none.
In this list, every occurrence of
.BR /fo ,
.BR \-fo ,
.BR /nologo ,
or
.B \-nologo
followed by a space is removed, and every occurrence of the text of
.I object
becomes
.BI \-Fo object .obj\fR.
.I cl
writes no object, but leaves the preprocessed script, a
.B .i
file named after the script, in that directory.
.IP 2. 4
If
.I cl
fails, exit with its status.
Otherwise write
.IR depfile ,
described below.
.IP 3. 4
Run
.I rc
with the
.I argument
list in the current directory, and exit with its status.
If the list contained
.B /nologo
or
.B \-nologo
followed by a space,
.I rc
gets a single
.B /nologo
before it.
.PP
The standard output and standard error of each tool are captured together.
Lines that start with
.I prefix
name included files and are dropped, as is the first other line that
starts with the part of
.I source
after its last backslash, which
.I cl
prints first.
This is the only use of
.IR source .
When the tool fails, the remaining lines are written to standard output.
When it succeeds they are discarded, so warnings never appear.
.PP
.I prefix
is the localized text that
.B /showIncludes
puts before each included file, such as
.B "Note: including file:"
in English.
CMake passes the value of
.BR CMAKE_CL_SHOWINCLUDES_PREFIX ,
which it detects when it tests the compiler, and which is empty if that
detection fails.
An empty
.I prefix
matches every line, so every line counts as an included file and nothing
is printed, even when the tool fails.
.SS Command line
.B cmcldeps
splits its command line itself, not by the C runtime rules.
Arguments are separated by spaces.
Double quotes start and end runs in which spaces do not separate, and are
removed only when they enclose the whole argument.
Backslashes are not special.
Every argument up to and including
.I rc
must be followed by a space.
The rest of the line is the
.I argument
list, which is split by the Microsoft C runtime rules when a tool runs.
.PP
The first argument must be
.BR RC .
The usage message also names
.B C
and
.BR CXX ,
but they are rejected.
Errors are reported on standard error as
.B "ninja: FATAL:"
followed by the reason and a usage summary.
.SS Dependency file
.I depfile
is written only when
.I cl
succeeds, and replaces any existing file.
An empty
.I depfile
argument writes none.
If it cannot be created,
.B cmcldeps
carries on without it.
It is one Make rule with
.I object
as the target and each included file on its own line:
.PP
.RS 4
.EX
CMakeFiles\e\eapp.dir\e\eapp.rc.res: \e
C:\e\esdk\e\eum\e\ewinres.h \e
gen\e\eversion.h \e
C:\e\esrc\e\emy\e app\e\eresource.h \e
.EE
.RE
.PP
An empty line ends the file, and lines end in LF.
Each file name is the rest of its line after
.IR prefix ,
without leading spaces or a final carriage return.
The names are sorted and exact duplicates dropped, then forward slashes
become backslashes, and the current directory is removed from the start
of a name, matching case.
Each backslash is doubled and each space escaped with a backslash.
.I source
itself is not listed.
.SH ENVIRONMENT
.TP
.B PATH
Searched for
.I cl
and
.I rc
when they are named without a directory.
The current directory is not searched.
.SH EXIT STATUS
.TP
.B 0
Each tool succeeded or could not be started.
.TP
.B 1
Invalid command line.
.TP
.I n
.I cl
or
.I rc
failed with status
.IR n .
.SH EXAMPLES
List the commands in a CMake build directory that use
.BR cmcldeps :
.PP
.RS 4
.EX
$ ninja \-t commands | grep cmcldeps
.EE
.RE
.PP
Compile
.I app.rc
to
.I app.res
with the
.B cl
and
.B rc
found on
.BR PATH ,
writing the headers it includes to
.IR app.res.d :
.PP
.RS 4
.EX
$ cmcldeps RC app.rc app.res.d app.res "Note: including file:" \e
cl rc /fo app.res app.rc
.EE
.RE
.SH NOTES
With the kit's own GCC toolchain, CMake compiles resource scripts with
.BR windres (1)
and never runs
.BR cmcldeps .
It runs only when the kit's
.B cmake
uses the Ninja generator with MSVC or a compatible compiler, and the kit's
.B cmake
picks Ninja by default even when Visual Studio is installed.
Running it by hand is rarely useful, except to repeat a failing build step.
.PP
If
.I cl
or
.I rc
cannot be started, for example because it is not found,
.B cmcldeps
prints nothing and treats the tool as successful.
The same happens to
.I cl
when the directory of
.I object
does not exist.
Without
.IR cl ,
it writes no
.I depfile
but still runs
.IR rc .
Without
.IR rc ,
it exits with status 0 although nothing wrote
.IR object .
.PP
Because
.I cl
runs in the directory of
.I object
and
.I rc
in the current directory, a relative path in the
.I argument
list means different files to the two tools, and a relative
.I cl
path is resolved from the directory of
.IR object .
.PP
Tool output lines that end in CR LF are written with an extra CR.
.SH SEE ALSO
.BR cmake (1),
.BR windres (1),
.BR cmake\-generators (7)

498
man/man1/gendef.1 Normal file
View File

@@ -0,0 +1,498 @@
.TH GENDEF 1 2026-10-20 "w64devkit" "w64devkit Manual"
.SH NAME
gendef \- write a module-definition file from the exports of a DLL
.SH SYNOPSIS
.B gendef
.RB [ \-a ]
.RB [ \-f ]
.RB [ \-r ]
.RB [ \-I
.IR dir ]...
.RB [ \-\-no\-include\-current\-dir ]
.RB [ \- ]
.IR file ...
.SH DESCRIPTION
.B gendef
reads the export table of each
.IR file ,
a PE image such as a DLL, and writes a module-definition (DEF) file that
lists its exports, from which
.BR dlltool (1)
makes an import library.
It is gendef 1.1, from Mingw-w64 14.0.0.
It reads 32-bit (PE32) and 64-bit (PE32+) images of any machine type.
In a 32-bit x86 image it also guesses the stdcall decoration of each
function, which the export table lacks.
.PP
For each
.IR file ,
.B gendef
writes a DEF file in the current directory, named for the part of
.I file
after its last slash or backslash, with its final extension, if any,
replaced by
.BR .def ,
so
.I lib/foo.dll
gives
.IR foo.def .
An existing file of that name is replaced.
With
.BR \- ,
it writes every DEF file to standard output instead.
A file without exports produces no output and no message.
.SS Output format
A DEF file begins with
.PP
.RS 4
.EX
LIBRARY "\fIname\fR"
EXPORTS
.EE
.RE
.PP
where
.I name
is the DLL name recorded in the export table, which may differ from the
file name.
A line for each export follows, in ordinal order, with these parts in
this order, each but the first only where it applies:
.TP
.I name
The export name, in double quotes when it contains a dot.
An export without a name is
.BI ord_ n\fR,
where
.I n
is its ordinal.
.TP
.BI @ size
The argument size in bytes of a stdcall function in a 32-bit x86 image,
as described under
.B Decorations
below.
.TP
.BI "= " target
For a forwarded export, the export it forwards to, as
.IB dll . name
or
.IB dll .# ordinal\fR.
.TP
.BI @ ordinal " NONAME"
For an export without a name.
Named exports are written without their ordinals, so an import library
made from the file imports them by name.
.TP
.B DATA
For an export that is data rather than a function.
.TP
.B PRIVATE
For these names, which programs do not import, so that an import library
leaves them out:
.BR DllCanUnloadNow ,
.BR DllEntryPoint ,
.BR DllGetClassFactoryFromClassString ,
.BR DllGetClassObject ,
.BR DllGetDocumentation ,
.BR DllInitialize ,
.BR DllInstall ,
.BR DllMain ,
.BR DllRegisterServer ,
.BR DllRegisterServerEx ,
.BR DllRegisterServerExW ,
.BR DllUnload ,
.BR DllUnregisterServer ,
.BR RasCustomDeleteEntryNotify ,
.BR RasCustomDial ,
.BR RasCustomDialDlg ,
and
.BR RasCustomEntryDlg .
.TP
.BI "== " name
The name as the DLL exports it, for some decorated names, as described
under
.B Decorations
below.
.TP
.BI "; " comment
A warning about a guess, as described under
.B Comments
below.
.PP
Lines end with CRLF.
.SS Data exports
An export is
.B DATA
when any of these hold:
.IP \(bu 2
Its address lies in a section that is not executable and is readable or
discardable, such as
.BR .data ,
.BR .rdata ,
or
.BR .bss .
.IP \(bu 2
A base relocation applies at its address, so that it holds a pointer.
.IP \(bu 2
Its name begins with
.BR ??_7 ,
as an MSVC virtual function table does.
.IP \(bu 2
In a 32-bit x86 image, its first instruction is one that
.B gendef
does not recognize, which wrongly marks some functions as data.
.IP \(bu 2
A hint file marks it
.BR DATA .
.SS Decorations
In a 32-bit x86 image,
.B gendef
writes the argument size of each stdcall function as a decoration,
.BI @ n\fR,
after its name, as in
.BR mul@8 .
.BR dlltool (1)
with
.B \-k
then makes an import library whose symbols carry the decoration, as the
compiler references them, but that imports the names without it.
.PP
To find the size,
.B gendef
decodes the function's machine code from its entry point.
It follows unconditional jumps and steps over calls, and when a path
ends without a return, as at an indirect jump, it tries the targets of
the conditional jumps it passed.
The first return instruction it reaches decides:
.BI "ret " n
gives the size
.IR n ,
and a plain
.BR ret ,
which both cdecl functions and stdcall functions without arguments use,
leaves the size unknown, unless given
.BR \-a .
Since calls are stepped over, after a call to a function that does not
return, the search runs on into whatever code follows.
When the size is still unknown and the code jumps through the import
address table to an imported function, the size of that function is
looked up in a hint file.
.PP
The size is written as follows, with an unknown size taken as 0 in the
comparisons:
.IP \(bu 2
A name of the form
.BI _ name @ n\fR,
where
.I n
is the size, loses its underscore and is followed by
.BI "== _" name @ n\fR,
as in
.BR "mul@8 == _mul@8" .
.IP \(bu 2
A fastcall name,
.BI @ name @ m\fR,
is kept and followed by
.BI "== @" name @ m
when
.I m
is the size plus 8, or when the size is 0 and
.I m
is 0, 4, or 8.
.IP \(bu 2
A C++ name, which begins with
.BR ? ,
is kept, and a known size goes in a comment.
.IP \(bu 2
Otherwise a known size is appended, even to a name that already has a
decoration, so
.B mul@8
becomes
.BR mul@8@8 .
.PP
Other images have no decorations: names are written as exported.
.SS Hint files
For each forwarded export, and, in a 32-bit x86 image, for each function
whose size is still unknown and that jumps to an imported function,
.B gendef
looks up the function forwarded to or imported in a hint file.
That is a DEF file for the other DLL, named for that DLL's name up to
its first dot, in lowercase, plus
.BR .def .
For an import from
.I KERNEL32.dll
or a forward to
.BR KERNEL32.GetTickCount ,
it is
.IR kernel32.def .
A forward to an ordinal, as in
.BR KERNEL32.#100 ,
looks up the name
.BR ord_100 ,
but a function imported by ordinal is looked up under the part of its
DLL's name after the first dot, such as
.BR dll .
.PP
Hint files are looked for in the current directory, unless given
.BR \-\-no\-include\-current\-dir ,
then in each
.B \-I
directory, the last given first.
Since
.B gendef
writes its DEF files in the current directory, one written earlier in a
run serves as a hint file for the files after it.
Each hint file is read at most once per run, so one that
.B gendef
replaces after reading it keeps its old contents for the rest of the
run.
.PP
A line of a hint file matches when it begins with the function's name
followed by
.BR @ ,
white space, or the end of the line.
The digits right after that character give the size, and
.B DATA
anywhere later in the line marks the export as data.
A name without a decoration gives 0, including one that
.B gendef
wrote for a function whose size it could not find.
In a file with LF line endings, a name alone on its line takes its size
and
.B DATA
from the next line.
The first line of a hint file never matches, and neither does a line
that begins with white space.
Outside 32-bit x86 images, only
.B DATA
is used.
.SS Comments
A comment at the end of an export's line flags a guess:
.IP \(bu 2
.BI "; has WINAPI (@" n )
follows a C++ name whose function has the size
.IR n .
.IP \(bu 2
.BI "; Check!!! return value is from " name " in " dll\fR,
or
.BI "; Check!!! return value is from ord " n " in " dll\fR,
follows a function that jumps to a function imported from
.I dll
by name or by ordinal, when no hint file gave the size.
Despite the wording, it is the argument size that is unknown.
.IP \(bu 2
.BI "; Check!!! forwards to " target
follows a forwarded export that is not data and either has no name or,
in a 32-bit x86 image, has an unknown size.
It is written even with
.BR \-f .
.IP \(bu 2
.B "; Check!!! Couldn\(aqt determine function argument count.\&"
.B "Function doesn\(aqt return.\&"
follows a function in which no return instruction was found.
.SH OPTIONS
Each option is a separate argument.
Options cannot be grouped, an option's argument is the next argument,
and the long options take no
.BR = .
Options apply to every file, wherever they appear.
Any other argument is a file, including an unknown option and
.BR \-\- .
.TP
.B \-
Write the DEF files to standard output, one after another, instead of
to files.
Standard input cannot be read.
.TP
.BR \-h ", " \-\-help
Print a usage message on standard error and exit without reading any
file.
With no arguments,
.B gendef
does the same.
.TP
.BR \-a ", " \-\-assume\-stdcall
In a 32-bit x86 image, take a function that returns with a plain
.B ret
to be stdcall without arguments, and decorate it with
.BR @0 .
Since cdecl functions return the same way, they get
.B @0
too, so this suits a DLL whose functions are all stdcall, such as a
Windows system DLL.
.TP
\fB\-I \fIdir\fR, \fB\-\-include\-def\-path \fIdir\fR
Look for hint files in
.IR dir .
As the last argument,
.B \-I
prints a message on standard error, without a newline, and is otherwise
ignored.
.TP
.B \-\-no\-include\-current\-dir
Do not look for hint files in the current directory.
.TP
.BR \-f ", " \-\-no\-forward\-output
Omit the
.BI "= " target
part of forwarded exports, which are still listed.
.TP
.BR \-r ", " \-\-disable\-fs\-redirector
Disable WOW64 file system redirection, so that a 32-bit
.B gendef
on 64-bit Windows reads the 64-bit DLLs in
.I system32
instead of the 32-bit DLLs in
.IR SysWOW64 .
Where there is no redirection to disable, as in the 64-bit kit, it
prints a message on standard error and has no other effect.
.SH EXIT STATUS
.TP
.B 0
Success, and also when a file cannot be read or is not a PE image, or
its DEF file cannot be written.
.PP
Problems are reported on standard error, and
.B gendef
goes on to the next file:
.PP
.RS 4
.EX
*** [\fIfile\fR] failed to open()
*** [\fIfile\fR] unable to allocate \fIsize\fR bytes
*** [\fIfile\fR] not a PE(+) file
*** [\fIfile\fR] no PE(+) signature
*** [\fIfile\fR] no PE(+) optional header
* failed to create \fIdeffile\fR ...
.EE
.RE
.PP
where
.I file
is the argument and
.I deffile
the name of its DEF file.
The second is also reported for an empty file and for a read error.
.SH EXAMPLES
Write
.I foo.def
for
.IR foo.dll :
.PP
.RS 4
.EX
$ gendef foo.dll
.EE
.RE
.PP
Print the DEF file of a 32-bit DLL, with a stdcall function
.B mul
that takes two
.B int
arguments, and a cdecl function
.BR add :
.PP
.RS 4
.EX
$ gendef \- demo.dll
LIBRARY "demo.dll"
EXPORTS
DllMain@12 PRIVATE
add
counter DATA
mul@8
ord_9 @9 NONAME
.EE
.RE
.PP
Make an import library for a 64-bit DLL:
.PP
.RS 4
.EX
$ gendef foo.dll
$ dlltool \-d foo.def \-l libfoo.a
.EE
.RE
.PP
Make an import library for that 32-bit DLL in the 64-bit kit, with
.B \-k
to remove the decorations from the imported names:
.PP
.RS 4
.EX
$ gendef demo.dll
$ i686\-w64\-mingw32\-dlltool \-k \-d demo.def \-l libdemo.a
.EE
.RE
.PP
Write DEF files for two 32-bit DLLs, where
.I wrapper.dll
forwards
.B plus
to
.B add
in
.IR base.dll ,
so that
.IR base.def ,
written first, gives the size of the forwarded function:
.PP
.RS 4
.EX
$ gendef base.dll wrapper.dll
$ cat wrapper.def
LIBRARY "wrapper.dll"
EXPORTS
plus@8 = base.add
twice@8
.EE
.RE
.SH NOTES
The kit also installs
.B gendef
under its target-prefixed name, such as
.BR x86_64\-w64\-mingw32\-gendef ,
and the 64-bit kit adds
.BR i686\-w64\-mingw32\-gendef .
Each runs the same program, with no added options, and reads 32-bit and
64-bit images alike.
.PP
Unlike upstream gendef, the kit's build starts each DEF file at
.BR LIBRARY ,
without a comment header, which upstream uses to say when the file needs
.BR "dlltool \-k" ,
and prints no progress message for each image.
.PP
.BR dlltool (1)
cannot read a forward to an ordinal, as in
.BR "= KERNEL32.#100" :
it reports a syntax error and leaves that export and every later one out
of the import library, so use
.B \-f
for such a DLL.
It reads the decoration of a name in quotes, as in
.BR \(dqa.b\(dq@4 ,
as an ordinal, so the decoration is lost.
.PP
When several names share one ordinal, only the last of them in the
image's name table, which is sorted, is written.
.PP
When a DEF file cannot be created, the exports of that image are written
at the start of the next DEF file instead, with their decorations
guessed from the wrong image, which can also mark them as data.
.PP
A drive prefix stays in the output name:
.I d:foo.dll
gives
.IR d:foo.def ,
in the current directory of drive D.
.PP
Paths must be representable in the ANSI code page.
Each file is read whole into memory.
.B gendef
trusts the offsets in an image, so a malformed image can crash it.
.SH SEE ALSO
.BR dlltool (1),
.BR ld (1),
.BR objdump (1),
.BR peports (1)

786
man/man1/makensis.1 Normal file
View File

@@ -0,0 +1,786 @@
.TH MAKENSIS 1 2026-10-20 "w64devkit" "w64devkit Manual"
.SH NAME
makensis \- compile NSIS scripts into Windows installers
.SH SYNOPSIS
.B makensis
.RI [ option " | " script " |"
.BR \- "] ..."
.SH DESCRIPTION
.B makensis
compiles scripts for NSIS 3.13, the Nullsoft Scriptable Install System,
into a Windows installer: a stub program followed by the compressed
files, settings, and code that the scripts describe.
Scripts are conventionally named
.IR *.nsi ,
and the headers they include
.IR *.nsh .
Progress messages and warnings go to standard output, and errors to
standard error.
.PP
The arguments are processed in order, so an option affects only the
scripts after it:
.B makensis /DX a.nsi
defines
.B X
for
.IR a.nsi ,
but
.B makensis a.nsi /DX
does not.
Several scripts are treated as one concatenated script that produces a
single installer.
A
.I script
that cannot be opened is tried again with
.B .nsi
appended.
A
.I script
named
.B \-
is read from standard input.
.PP
Before reading each script file,
.B makensis
changes to its directory, so that relative paths in the script are
relative to the script.
The change remains in effect, so a relative
.I script
path later on the command line is relative to the previous script.
.PP
The installer is written to the path named by the script's
.B OutFile
command, replacing any file there.
A relative path is taken from the current directory when the installer
is written, which is normally the directory of the last script.
Without
.BR OutFile ,
the path is the full path of the first script file up to its last
period, if any, followed by
.BR .exe .
That period may be in a directory name.
A script read from standard input gives no default.
.PP
Before the first script,
.B makensis
reads two files of script code common to every installer, each only if
it exists:
.I nsisconf.nsh
in the directory named by
.BR NSISCONFDIR ,
or else in the parent of the compiler's directory,
.IR share/nsis ,
even when
.B NSISDIR
is set, and then
.IR %APPDATA%\ensisconf.nsh .
.B /NOCONFIG
skips both.
.SS Scripts
A script is a sequence of commands, one per line.
A line ending in a backslash continues on the next, and
.B ;
and
.B #
begin comments, as does
.B /*
up to
.BR */ .
Attributes such as
.BR Name ,
.BR OutFile ,
and
.B RequestExecutionLevel
configure the installer,
.B Section
and
.B Function
blocks hold the instructions it runs, and
.B Page
commands choose its pages.
Commands beginning with
.BR ! ,
such as
.BR !include ,
.BR !define ,
.BR !ifdef ,
.BR !macro ,
and
.BR !system ,
are preprocessor commands, run at compile time.
In arguments,
.BI ${ name }
expands a symbol from
.B !define
or
.BR /D ,
.BI $% name %
an environment variable at compile time, and
.BI $ name
a variable when the installer runs.
.B /CMDHELP
prints the syntax of every command.
.SS Data directory
.B makensis
finds its stubs, plugins, and headers in its data directory: the parent
of the directory that holds the compiler, which is
.I share/nsis
in the kit, or
.B NSISDIR
when set.
Scripts see it as
.BR ${NSISDIR} .
It holds:
.TP
.I Stubs
The installer stubs, one for each compressor, solid or not, and target,
named like
.IR lzma_solid\-amd64\-unicode .
The compressors are
.BR zlib ,
the default,
.BR bzip2 ,
and
.BR lzma ,
chosen with
.BR SetCompressor .
Also
.IR uninst ,
the default uninstaller icon.
.TP
.IR Plugins/amd64\-unicode ", " Plugins/x86\-unicode
The plugin DLLs of the NSIS distribution, such as
.BR System ,
.BR nsDialogs ,
and
.BR nsExec ,
for each target.
A script calls their functions as
\fIplugin\fB::\fIfunction\fR.
.TP
.I Include
The headers, such as
.I MUI2.nsh
for the Modern UI and
.I LogicLib.nsh
for structured control flow.
.B !include
searches the current directory, then this directory, then those added by
.BR !addincludedir .
.TP
.I Contrib
Files the headers use: Modern UI pages, graphics, language files, and
alternative user interface resources.
.TP
.I Bin
The compiler,
.IR makensis.exe ,
and
.I RegTool\-amd64.bin
.RI ( RegTool\-x86.bin
in the x86 kit), which
.I Library.nsh
embeds to register DLLs after a reboot.
.SS Targets
The target is the processor and character set of the installer:
.B amd64\-unicode
or
.BR x86\-unicode .
The x64 kit has stubs and plugins for both and defaults to
.BR amd64\-unicode .
The x86 kit has only
.BR x86\-unicode .
A script selects a target with a command such as
.BR "Target x86\-unicode" ,
before any file is compressed.
.B makensis
also knows
.B x86\-ansi
and
.BR arm64\-unicode ,
but the kit has no stubs for them, so selecting them, including with
.BR "Unicode false" ,
fails with an error ending in
.BR "(adequate stub not found?)" .
.PP
.B CPU amd64
and
.B CPU x86
also select a target, but
.B CPU x86
chooses between
.B x86\-ansi
and
.B x86\-unicode
by a flag that is uninitialized unless an earlier command changed the
target from an x86 one.
It may therefore select
.B x86\-ansi
and fail, as it does in the x64 kit.
Use
.B Target
instead.
.SS Predefined symbols
.B /HDRINFO
lists the symbols defined before any script, most of which describe how
.B makensis
was built.
These are the most useful:
.TP
.B NSISDIR
The data directory.
.TP
.B NSIS_VERSION
The version, such as
.BR v19\-Oct\-2026.cvs ;
see
.BR NOTES .
.TP
.B NSIS_PACKEDVERSION
The version as a number,
.BR 0x03012666 .
.TP
.B NSIS_CPU
.B amd64
or
.BR x86 ,
from the target.
.TP
.B NSIS_PTR_SIZE
The size of a pointer in the installer,
.B 8
or
.BR 4 .
.TP
.B NSIS_CHAR_SIZE
.BR 2 ,
the size of a character in the installer.
.TP
.BR NSIS_AMD64 ", " NSIS_IX86
.B NSIS_AMD64
is
.B 1
for
.BR amd64\-unicode ,
and
.B NSIS_IX86
is
.B 400
for
.BR x86\-unicode .
Only one is defined.
.TP
.B NSIS_UNICODE
Defined, since every available target is Unicode.
.TP
.BR NSIS_WIN32_MAKENSIS ", " NSIS_UNICODE_MAKENSIS
Defined.
.TP
.B NSIS_MAKENSIS64
Defined in the x64 kit, whose compiler is a 64-bit program.
.PP
The target symbols change when the script changes the target.
Standard predefines such as
.B __FILE__
and
.B __LINE__
are also available.
.SH OPTIONS
Each option begins with
.B /
or
.BR \- ,
so
.B /NOCD
and
.B \-NOCD
are the same, and option names are case-insensitive.
An argument shown attached, as in
.BR /V2 ,
must be attached, and others are the next argument.
After
.BR \-\- ,
every argument is a script, so
.B \-
then names a file, and a script path beginning with
.B /
or
.B \-
can follow.
.PP
.BR /NOTIFYHWND ,
.BR /O ,
.BR /OUTPUTCHARSET ,
.BR /PPO ,
.BR /RAW ,
.BR /SAFEPPO ,
.BR /VERSION ,
and
.B /WX
take effect only before the first script file name, not counting
.BR \- ,
and before
.BR \-\- .
Later, they are ignored, except
.BR /VERSION ,
which is then unrecognized.
An unrecognized option stops the processing of arguments:
.B makensis
prints the usage message and exits with status 1 without writing an
installer.
.TP
\fB/CMDHELP\fR [\fIitem\fR]
Print the syntax of the script command
.IR item ,
or of every command, on standard output.
The next argument, if there is one, is always taken as
.IR item ,
even when it looks like an option or a script.
An unknown
.I item
prints an error, but processing continues.
.TP
.B /HDRINFO
Print the sizes of the installer's header structures and every symbol
defined so far, including the build options of
.BR makensis .
.TP
.B /LICENSE
Print the NSIS license.
.TP
.B /VERSION
Print the version, without a newline, and exit with status 0.
Of the other arguments, only the options listed above that precede it
take effect.
.TP
.B /HELP
Print the usage message on standard output.
.TP
.BI /P n
Set the priority of the process:
.B 0
idle,
.B 1
below normal,
.B 2
normal,
.B 3
above normal,
.B 4
high, or
.B 5
realtime, which also prints a warning.
.TP
.BI /V n
Set the verbosity:
.B 0
prints nothing,
.B 1
only errors,
.B 2
also warnings,
.B 3
also information, the default, and
.B 4
also a line for each script command processed.
Given before the first script,
.B /V3
or
.B /V4
first prints a banner with the version, unless
.B /PPO
or
.B /SAFEPPO
is given.
.BR /CMDHELP ,
.BR /HDRINFO ,
and
.B /LICENSE
print nothing below 3.
.TP
.B /WX
Treat warnings as errors: the first warning ends
.B makensis
with status 1.
.TP
.BI /O file
Write all output, including errors, to
.IR file ,
replacing its contents.
If it cannot be opened,
.B makensis
prints a warning and uses standard output.
.TP
.B /LAUNCH
After writing the installer, run it as if it were opened in Explorer,
without waiting for it.
.TP
.B /PAUSE
Before exiting, print
.B MakeNSIS done \- hit enter to close...\&
and wait for a newline, carriage return, or Escape on standard input,
forever if standard input is at end of file.
A
.B \-
argument after
.B /PAUSE
cancels it.
.TP
.B /NOCONFIG
Do not read the
.I nsisconf.nsh
files.
It must come before the first script.
.TP
.B /NOCD
Do not change to the directory of each script that follows.
.TP
\fB/INPUTCHARSET\fR \fIcharset\fR, \fB/ICS\fR \fIcharset\fR
Read the scripts that follow, when they have no byte order mark, in
.IR charset :
.B ACP
for the ANSI code page, the default;
.B OEM
for the OEM code page;
.BI CP n
for code page
.IR n ;
.BR UTF8 ;
or
.BR UTF16LE .
.B UTF16BE
also selects UTF-16LE.
Names are case-insensitive, and
.B UTF
may be followed by a hyphen or an underscore.
.B AUTO
selects the default, and so does any other name, with a warning.
Files read by
.B !include
are not affected.
.TP
\fB/OUTPUTCHARSET\fR \fIcharset\fR, \fB/OCS\fR \fIcharset\fR
Write output that does not go to a console, including the
.B /O
log, in
.IR charset ,
named as for
.BR /INPUTCHARSET ,
or as
.B UTF8SIG
for UTF-8 with a byte order mark, or
.B UTF16LEBOM
for UTF-16LE with one.
The default is
.BR ACP .
When standard output or standard error is a file that already begins
with a byte order mark, and that
.B makensis
can also read, it uses that file's encoding instead.
The kit's shell opens redirected files for writing only, so this does
not apply there.
An unknown
.IR charset ,
including
.BR AUTO ,
prints the usage message and exits with status 1.
.TP
.B /RAW
Like
.BR "/OUTPUTCHARSET UTF16LE" ,
but never take the encoding from a byte order mark.
.TP
.B /PPO
Preprocess only: write the script to standard output with symbols
substituted, macros expanded, and conditional blocks resolved, then exit
without writing an installer.
Preprocessor commands run as usual, except that
.BR !packhdr ,
.BR !finalize ,
and
.B !uninstfinalize
are written out instead.
The verbosity is at most 1.
.TP
.B /SAFEPPO
Like
.BR /PPO ,
but also write out, instead of running,
.BR !system ,
.BR !execute ,
.BR !makensis ,
.BR !appendfile ,
.BR !delfile ,
and
.BR !tempfile .
.TP
\fB/D\fIname\fR[\fB=\fIvalue\fR]
Define the symbol
.I name
as
.IR value ,
or as empty, for the scripts that follow, like
.BR !define .
A name already defined, such as
.B NSISDIR
or one from an earlier
.BR /D ,
keeps its value.
A later
.B !define
of the same name is an error.
.TP
.BI /X command
Process
.I command
as a line of script, in its place among the arguments.
Messages that give its location name the file
.B <command line>
and, as the line, its position among the arguments plus one.
Commands before the first script run before the
.I nsisconf.nsh
files are read.
Without any script, the
.B /X
commands make up the whole script, and no
.I nsisconf.nsh
is read.
.TP
.BI "/NOTIFYHWND " hwnd
Report to the window whose handle is the decimal number
.IR hwnd ,
through the protocol of the MakeNSISW front end, which the kit does not
include.
It is ignored when
.I hwnd
is not a window.
.SH ENVIRONMENT
.TP
.B APPDATA
The directory of the per-user
.IR nsisconf.nsh ,
read after the main one.
.TP
.B COMSPEC
The command interpreter, normally
.BR cmd.exe ,
that runs the commands of
.BR !system ,
.BR !packhdr ,
.BR !finalize ,
and
.BR !uninstfinalize .
When it is empty,
.B CMD.EXE
is used, and when it is unset, these commands terminate
.B makensis
abnormally.
.TP
.B NSISCONFDIR
The directory of the main
.IR nsisconf.nsh ,
instead of the parent of the compiler's directory.
.TP
.B NSISDIR
The data directory, instead of the parent of the compiler's directory.
It does not move the main
.IR nsisconf.nsh .
.TP
.BR TMP ", " TEMP
The directory for temporary files, as chosen by
.BR GetTempPath .
.PP
Scripts can read any variable at compile time as
.BI $% name %\fR.
.SH EXIT STATUS
.TP
.B 0
Success: the installer was written, preprocessing finished, or
.B /VERSION
ran.
Without a script or
.B /X
command,
.BR /HDRINFO ,
.BR /HELP ,
.BR /LICENSE ,
or a valid
.B /CMDHELP
also exits with 0.
.TP
.B 1
An error, such as a script that cannot be opened, an error in a script
or an
.IR nsisconf.nsh ,
a warning under
.BR /WX ,
an unrecognized option, no script, missing stubs, or Ctrl+C.
.TP
.B 382
The launcher could not start the compiler.
It prints a message beginning
.B w64devkit (alias):
on standard error.
The kit's shell sees it as 126, its low byte.
.SH EXAMPLES
Write a script for an installer that copies
.I hello.exe
into a directory the user chooses, without asking for administrator
rights, and compile it into
.IR hello\-setup.exe :
.PP
.RS 4
.EX
$ cat >hello.nsi <<\(aqEOF\(aq
Name "Hello"
OutFile "hello\-setup.exe"
InstallDir "$LOCALAPPDATA\eHello"
RequestExecutionLevel user
Page directory
Page instfiles
Section
SetOutPath "$INSTDIR"
File "hello.exe"
SectionEnd
EOF
$ makensis hello.nsi
.EE
.RE
.PP
Build a 32-bit installer with the x64 kit, under another name.
The
.B Target
command must come before the script, and the
.B OutFile
command after it, to override the script's own:
.PP
.RS 4
.EX
$ makensis "/XTarget x86\-unicode" hello.nsi \e
"/XOutFile hello32\-setup.exe"
.EE
.RE
.PP
Print only warnings and errors, and define
.B VERSION
for a script that uses
.BR ${VERSION} :
.PP
.RS 4
.EX
$ makensis /V2 /DVERSION=1.2.3 hello.nsi
.EE
.RE
.PP
Compress with solid LZMA without editing the script:
.PP
.RS 4
.EX
$ makensis "/XSetCompressor /SOLID lzma" hello.nsi
.EE
.RE
.PP
Print the syntax of a command:
.PP
.RS 4
.EX
$ makensis /CMDHELP SetCompressor
Usage: SetCompressor [/FINAL] [/SOLID] (zlib|bzip2|lzma)
.EE
.RE
.PP
Show the script after preprocessing, without letting it run programs or
change files:
.PP
.RS 4
.EX
$ makensis /SAFEPPO hello.nsi >hello.txt
.EE
.RE
.SH NOTES
The kit's
.I bin/makensis.exe
is a launcher that runs
.I share/nsis/Bin/makensis.exe
with the same arguments, waits for it, and exits with its status.
The launcher ignores Ctrl+C, leaving it to the compiler, which then
exits with status 1.
.PP
The kit builds NSIS 3.13 without a release version, so
.B /VERSION
and
.B ${NSIS_VERSION}
give the date of the build, as in
.BR v19\-Oct\-2026.cvs ,
and
.B ${NSIS_PACKEDVERSION}
is
.BR 0x03012666 ,
below the
.B 0x03013000
of a 3.13 release.
A script that requires NSIS 3.13 or later by comparing
.B ${NSIS_PACKEDVERSION}
rejects the kit.
.PP
The kit omits the NSIS documentation and examples,
.IR nsisconf.nsh ,
the MakeNSISW front end, zip2exe, MakeLangId, the VPatch patch generator
GenPat, and the
.B x86\-ansi
and
.B arm64\-unicode
stubs and plugins.
The x64 kit has only
.IR RegTool\-amd64.bin ,
so an
.B x86\-unicode
installer cannot use
.B InstallLib
from
.I Library.nsh
to register a library on reboot, as with the
.B REBOOT_PROTECTED
and
.B REBOOT_NOTPROTECTED
options:
.B makensis
stops with an error that RegTool is missing.
.PP
A script file named on the command line without a byte order mark is
read in the ANSI code page unless
.B /INPUTCHARSET
says otherwise, but the files it includes default to UTF-8.
Save scripts as UTF-8 with a byte order mark, or pass
.BR "/INPUTCHARSET UTF8" .
.PP
Output to a console goes through the Unicode console API, with warnings
in yellow and errors in red.
Other output, including the
.B /O
log, is in the ANSI code page unless
.B /OUTPUTCHARSET
says otherwise, and has CRLF line endings.
.PP
.BR !system ,
.BR !packhdr ,
.BR !finalize ,
and
.B !uninstfinalize
run their commands with
.BR cmd.exe ,
not the kit's
.BR sh .
.B !execute
and
.B !makensis
start programs directly.
.PP
Shells that rewrite arguments beginning with
.B /
as paths, such as those of MSYS2 and Git for Windows, garble the
.B /
forms of the options.
Use the
.B \-
forms there.

1144
man/man1/ninja.1 Normal file
View File

File diff suppressed because it is too large Load Diff

902
man/man1/widl.1 Normal file
View File

@@ -0,0 +1,902 @@
.TH WIDL 1 2026-10-20 "w64devkit" "w64devkit Manual"
.SH NAME
widl \- compile IDL into C headers, proxies, stubs, and type libraries
.SH SYNOPSIS
.B widl
.RI [ options ]
.I file
.br
.B widl \-\-dlldata\-only
.RI [ options ]
.IR name ...
.SH DESCRIPTION
.B widl
compiles an interface definition, written in Microsoft's interface
definition language (IDL), into the files that declare and implement
it: a header for C and C++, proxies and stubs in C that marshal calls to
COM objects and RPC servers in other processes, and type libraries.
It is Wine's IDL compiler, version 11.5, as distributed with Mingw-w64.
It reads the IDL dialect of Microsoft's MIDL, but its command line
differs.
.PP
.B widl
reads one IDL file,
.IR file ,
and cannot read standard input.
It runs the file through its own C preprocessor, then parses it.
An
.B import
statement reads another IDL file for its declarations, and the generated
header includes the header of that file, such as
.I unknwn.h
for
.IR unknwn.idl ,
instead of repeating them.
Each file is imported at most once.
Inside a
.B library
block,
.B importlib
reads the types of an existing type library, such as
.IR stdole2.tlb .
With
.BR \-\-acf ,
an attribute configuration file is read after
.IR file .
.PP
With no option that selects an output kind,
.B widl
writes every kind that the input calls for: the header and the interface
identifiers always, a type library when there is a
.B library
block, client and server stubs when there are RPC interfaces, a proxy, a
registration script, and
.I dlldata.c
when there are object interfaces that are neither
.B local
nor dispinterfaces, and metadata in Windows Runtime mode.
Only interfaces outside
.B library
blocks count.
.SS Output files
Each default file name is in the current directory, and is built from
.IR base ,
the part of
.I file
after its last forward slash, with a final
.B .idl
removed.
.TP
.IR base .h
The header, selected by
.B \-h
and named by
.BR \-H .
It declares the types, the interfaces as C++ classes and as C vtable
structures with call macros, and the GUIDs, and includes
.I rpc.h
and
.IR windows.h .
The proxy, stub, and local stub files include the header by this name.
Its include guard comes from the base name of the header file,
lowercased and with each character other than a letter or digit changed
to an underscore, as in
.BR __hello_h__ .
.TP
.IR base _i.c
The interface identifiers, selected by
.B \-u
and named by
.BR \-U :
definitions of the GUIDs of the COM interfaces, dispinterfaces, classes,
and libraries, such as
.BR IID_IHello .
.TP
.IR base _p.c
The proxy, selected by
.B \-p
and named by
.BR \-P :
proxies and stubs that marshal the object interfaces, for a proxy/stub
DLL.
Its symbols take their prefix from the base name of the proxy file
without
.BR _p.c ,
with each character other than a letter or digit changed to an
underscore, as in
.BR hello_ProxyFileInfo .
.TP
.I dlldata.c
The list of proxy files in a proxy/stub DLL, selected by
.B \-\-dlldata\-only
and named by
.BR \-\-dlldata .
It defines the DLL entry points
.B DllGetClassObject
and
.B DllCanUnloadNow
through macros in
.IR rpcproxy.h .
.B widl
also writes it while compiling an IDL file when no output kind is
selected.
It then adds the proxy to the list already in the file, if any, and
leaves the file alone if the proxy is listed.
When it adds to an existing file, it also writes
.BR "#define PROXY_DELEGATION" ,
which it otherwise writes only when an interface derives from an
imported or local interface other than
.BR IUnknown .
.TP
.IR base _c.c
The client stubs, selected by
.B \-c
and named by
.BR \-C ,
which send each call to an RPC interface to a server.
.TP
.IR base _s.c
The server stubs, selected by
.B \-s
and named by
.BR \-S ,
which receive calls and dispatch them to the server's functions.
.TP
.IR base .tlb
The type library, selected by
.B \-t
and named by
.BR \-T ,
in the MSFT format, or SLTG with
.BR \-\-oldtlb .
A file holds one library, unless its name ends in
.BR .res .
Then it is a binary resource file, with a
.B TYPELIB
resource for each library, numbered 1 or by the library's
.B id
attribute.
A name ending in
.B _t.res
also gets a
.B WINE_REGISTRY
resource with the registry entries of each library.
.TP
.IR base _r.rgs
The registration script, selected by
.BR \-r ,
in the text format of the ATL registrar: entries for the classes outside
libraries and their ProgIDs, and, when there is a class named
.BR PSFactoryBuffer ,
for the interfaces it marshals.
In Windows Runtime mode, entries for the activatable runtime classes
instead.
Only
.B \-o
names it, and a name ending in
.B .res
makes it a binary resource file with a
.B WINE_REGISTRY
resource.
.TP
.IR base .winmd
Windows Runtime metadata, selected by
.BR \-\-winmd .
Only
.B \-o
names it.
.SS Search paths
A quoted
.B #include
is first looked for in the directory of the including file, and an
.B import
in the directory of the importing file.
Then
.B widl
searches these directories, in order:
.IP 1. 4
Each
.B \-I
directory, in command line order.
.IP 2. 4
The kit's
.I include
directory, which holds the Mingw-w64 IDL files, such as
.IR unknwn.idl .
.B widl
finds it relative to its own executable, as
.IR bin/../include ,
so the kit works wherever it is unpacked.
.IP 3. 4
.I /w64devkit/include
on the current drive, from the kit's build prefix, or with
.BR \-\-sysroot ,
.IR dir/w64devkit/include .
.PP
.B \-\-nostdinc
omits the last two.
An
.B import
name that contains a
.B /
or
.B \e
is opened as given, relative to the current directory, without
searching.
.PP
A type library named by
.B importlib
is looked for in each
.B \-L
directory, first in a subdirectory named for the target, such as
.I x86_64\-windows
or
.IR i386\-windows ,
then in the directory itself.
Then it is looked for in the kit's
.I include
directory, which holds
.IR stdole2.tlb ,
and last in
.I /w64devkit/include/x86_64\-windows
on the current drive, named for the target.
.B \-\-nostdinc
omits the last two, and
.B \-\-sysroot
does not apply.
A type library is never looked for in the current directory or beside
.IR file ,
so one there needs
.B \-L
with its directory.
A name with a path is still joined to each directory, so an absolute
path is never found.
.SS Preprocessor
The preprocessor defines
.B __WIDL__
as the version, 0xb0500 for 11.5,
.B _WIN32
as 1, and
.BR __FILE__ ,
.BR __LINE__ ,
.BR __DATE__ ,
and
.BR __TIME__ .
.B \-D
cannot change
.B __WIDL__
or
.BR _WIN32 .
Neither
.B _WIN64
nor
.B __midl
is defined, whatever the target.
.SS Temporary files
Unless given
.B \-E
or
.BR \-N ,
.B widl
writes the preprocessed input, and each preprocessed import, into a
directory named
.B tmp
and 8 hex digits, which it creates in the current directory and removes
when it exits.
If access to the current directory is denied, it creates the directory
in
.BR TMPDIR ,
or else in
.I /tmp
on the current drive.
An error other than a syntax error, such as an import that cannot be
found, can leave the directory and its contents behind.
.SH OPTIONS
Options and
.I file
may come in any order.
A short option's argument may be attached, as in
.BR \-Iinclude ,
or be the next argument, and short options without arguments may be
grouped, as in
.BR \-hp .
A long option may begin with one dash or two, and its argument follows
.B =
or is the next argument.
A long option may be abbreviated to a unique prefix.
A word of two or more letters after one dash is tried as a long option
first, so
.B \-win32
means
.BR \-\-win32 ,
.B \-ro
means
.BR \-robust ,
and
.B \-pr
is rejected as ambiguous.
.B \-\-
ends the options.
.PP
The options that select an output kind are
.BR \-c ,
.BR \-\-dlldata\-only ,
.BR \-E ,
.BR \-h ,
.BR \-\-local\-stubs ,
.BR \-p ,
.BR \-r ,
.BR \-s ,
.BR \-t ,
.BR \-u ,
and
.BR \-\-winmd .
.TP
.BI \-\-acf= acf
Read the attribute configuration file
.I acf
after
.IR file .
It is preprocessed like
.IR file ,
and opened as given, without searching.
.B widl
never looks for an ACF on its own.
.TP
\fB\-\-align=\fIn\fR, \fB\-\-packing=\fIn\fR
Marshal structures as if their members are aligned to at most
.I n
bytes, which must be 2, 4, or 8.
The default is 8.
This affects only the proxies and stubs, not the header or type
libraries, so the C code must be compiled with the same packing.
.TP
.B \-app_config
Ignored, for compatibility with MIDL.
.TP
.BI "\-b " target
Generate code for
.IR target :
a CPU followed by a dash and further fields, as in
.B i686\-w64\-mingw32
or
.BR x86_64\-windows ,
or
.B mingw32
alone for i386.
The CPU field begins with one of
.BR i386 ,
.BR i486 ,
.BR i586 ,
.BR i686 ,
.BR i786 ,
.BR x86_64 ,
.BR amd64 ,
.BR arm ,
.BR aarch64 ,
.BR arm64 ,
or
.BR arm64ec ,
and a CPU alone, such as
.BR i686 ,
is rejected.
The target sets the pointer size, the calling convention details
encoded in proxies and stubs, and the subdirectory of the
.B importlib
search.
.BR \-m32 ,
.BR \-m64 ,
.BR \-\-win32 ,
and
.B \-\-win64
override its pointer size.
Without
.BR \-b ,
a command name that begins with a CPU and a dash, such as
.BR i686\-w64\-mingw32\-widl ,
selects that CPU, and otherwise the target is the CPU of
.B widl
itself: x86_64 in the 64-bit kit and i686 in the 32-bit kit.
The long form,
.BR \-\-target ,
takes no argument, so it cannot be used.
.TP
.B \-c
Write the client stubs,
.IR base _c.c.
.TP
.BI "\-C " file
Name the client stub file.
.TP
.BI "\-d " n
Set debugging flags to the bit mask
.IR n .
Bit 0x01 prints progress messages about type libraries on standard
error, and bits 0x08, 0x10, and 0x20 trace the preprocessor on standard
output and standard error.
The other bits listed by
.B \-\-help
have little or no effect.
Any nonzero
.I n
also makes both outputs unbuffered.
.TP
\fB\-D \fIname\fR[\fB=\fIvalue\fR]
Define the preprocessor macro
.I name
as
.IR value ,
or as empty, not 1, when there is no
.IR value .
A later
.B \-D
for the same name replaces an earlier one.
.TP
.BI \-\-dlldata= file
Name the dlldata file instead of
.IR dlldata.c .
This does not select it.
.TP
.B \-\-dlldata\-only
Write only the dlldata file, listing each operand as a proxy file by
its base name without
.BR .idl ,
and read no IDL file.
The file is written from scratch.
.TP
.B \-E
Preprocess
.I file
to standard output and exit, without parsing it, so
.B import
statements pass through unexpanded.
Other output options write nothing, but the file of each output kind
selected along with
.BR \-E ,
and the
.B \-\-local\-stubs
file, are deleted.
.TP
.B \-\-help
Print a usage message on standard error and exit.
.TP
.B \-h
Write the header,
.IR base .h.
.TP
.BI "\-H " file
Name the header file.
.TP
.BI "\-I " dir
Add
.I dir
to the include search path.
.TP
.BI "\-L " dir
Add
.I dir
to the
.B importlib
search path.
.TP
.BI \-\-local\-stubs= file
Write to
.I file
placeholders for the
.B _Proxy
and
.B _Stub
functions that each
.B call_as
attribute in an object interface requires.
Each returns
.BR E_NOTIMPL ,
or a zeroed value when the local method returns another type.
Only interfaces outside
.B library
blocks count.
.TP
.BR \-m32 ", " \-m64
Set a 32-bit or 64-bit pointer size, switching the target CPU to its
counterpart of that size, as from x86_64 to i386.
The argument may also be separate, as in
.BR "\-m 32" ,
and other values are ignored.
The pointer size appears in the proxies, stubs, type libraries, and
registry entries, and the proxies and stubs compile only for a target
of the same size.
Of
.BR \-m ,
.BR \-\-win32 ,
and
.BR \-\-win64 ,
the last one wins.
.TP
.B \-N
Do not preprocess
.IR file ,
the imported files, or the ACF.
The Mingw-w64 IDL files need preprocessing, so they cannot then be
imported.
.TP
.B \-\-nostdinc
Do not search the kit's
.I include
directory or
.I /w64devkit/include
for includes, imports, or type libraries.
.TP
.B \-\-ns_prefix
In Windows Runtime mode, put the C++ namespaces in the header inside
.BR "namespace ABI" ,
and add
.B ABI
to the C names, as in
.BR __x_ABI_CDemo_CIFoo .
.TP
.B \-\-oldnames
Name the RPC interface handles
\fIname\fB_ClientIfHandle\fR
and
\fIname\fB_ServerIfHandle\fR,
instead of
\fIname\fB_v\fIM\fB_\fIN\fB_c_ifspec\fR
and
\fIname\fB_v\fIM\fB_\fIN\fB_s_ifspec\fR,
where
.IR M . N
is the interface version.
The header adds the
.B \-\-prefix\-client
and
.B \-\-prefix\-server
prefixes to these names, but the stub files do not.
.TP
.B \-\-oldtlb
Write type libraries in the older SLTG format.
This fails for a 64-bit target, for a library that contains or depends
on a coclass, dispinterface, enum, union, or module, and for an
interface derived from one in a library named by
.BR importlib .
So any interface derived from
.B IDispatch
fails.
.TP
.BI "\-o " file
Name the output file.
When exactly one output kind is selected,
.I file
names it, unless that kind's own naming option was given.
With no option that selects an output kind, the kind is chosen by the
end of
.IR file :
.BR .h ,
.BR .tlb ,
.BR .winmd ,
.BR _p.c ,
.BR _c.c ,
.BR _s.c ,
.BR _i.c ,
.BR _r.res ,
.BR _t.res ,
.BR _l.res ,
or
.BR dlldata.c .
A
.B .winmd
ending also enables Windows Runtime mode, and a
.B dlldata.c
ending acts as
.BR \-\-dlldata\-only ,
so the operands are names, not IDL files.
Otherwise
.I file
is ignored, as it is for any other ending, such as
.BR _r.rgs .
The long form,
.BR \-\-output ,
takes no argument, so it cannot be used.
.TP
.BI "\-O " type
Select the stub style:
.B s
writes marshaling code for each method, and
.BR i ,
.BR ic ,
.BR if ,
and
.B icf
all select the default, interpreted stubs driven by format strings.
.TP
.B \-p
Write the proxy,
.IR base _p.c.
.TP
.BI "\-P " file
Name the proxy file.
.TP
.BI \-\-prefix\-all= prefix
Same as
.B \-\-prefix\-client
and
.B \-\-prefix\-server
together.
.TP
.BI \-\-prefix\-client= prefix
Prefix the names of the client stub functions, and of the client
interface handle, with
.IR prefix .
.TP
.BI \-\-prefix\-server= prefix
Prefix the names of the server functions that the server stubs call,
and of the server interface handle, with
.IR prefix .
.TP
.B \-r
Write the registration script,
.IR base _r.rgs.
.TP
.B \-robust
Ignored, for compatibility with MIDL.
.TP
.BI \-\-sysroot= dir
Search
.I dir/w64devkit/include
instead of
.IR /w64devkit/include .
It does not affect the kit's
.I include
directory or the
.B importlib
search.
.TP
.B \-s
Write the server stubs,
.IR base _s.c.
.TP
.BI "\-S " file
Name the server stub file.
.TP
.B \-t
Write the type library,
.IR base .tlb.
.TP
.BI "\-T " file
Name the type library file.
.TP
.B \-u
Write the interface identifiers,
.IR base _i.c.
.TP
.BI "\-U " file
Name the interface identifiers file.
There is no option to undefine a macro.
.TP
.B \-V
Print the version and exit.
.TP
.B \-W
Warn about preprocessor macro redefinitions,
.B #undef
of undefined macros, and ignored
.B #ident
lines.
The Mingw-w64 headers produce many such warnings.
.TP
.BR \-\-win32 ", " \-\-win64
Same as
.B \-m32
and
.BR \-m64 .
.TP
.B \-\-winmd
Write the Windows Runtime metadata,
.IR base .winmd,
and enable Windows Runtime mode.
.TP
.B \-\-winrt
Enable Windows Runtime mode, which accepts
.BR namespace ,
.BR runtimeclass ,
and the other Windows Runtime constructs.
A file can enable it with
.BR "#pragma winrt" ,
or
.B #pragma winrt ns_prefix
to set
.B \-\-ns_prefix
as well, and either pragma overrides
.BR \-\-ns_prefix .
.SH ENVIRONMENT
.TP
.B TMPDIR
The directory for temporary files, used only when access to the current
directory is denied.
.TP
.B TZ
The time zone of
.B __DATE__
and
.BR __TIME__ ,
read by the C runtime.
.PP
No other variable, such as
.BR INCLUDE ,
affects the search paths.
.SH EXIT STATUS
.TP
.B 0
Success.
.TP
.B 1
An invalid command line, an input file that cannot be opened, an error
in the input reported with its location, a type library, resource, or
metadata file that could not be written, an interrupt, or out of memory.
.TP
.B 2
Another error, reported as
.B error:
and a message, such as an invalid
.BR \-b ,
.BR \-O ,
or
.B \-\-packing
argument, a text output file that cannot be opened, a library named by
.B importlib
that cannot be found, or
.B \-\-oldtlb
for a 64-bit target.
.PP
An error in the input is reported on standard error as
.PP
.RS 4
.EX
\fIfile\fR:\fIline\fR:\fIcolumn\fR: error: \fImessage\fR
.EE
.RE
.PP
followed, except for preprocessor errors, by the source line with the
location marked.
When
.B widl
fails after it starts reading
.IR file ,
it deletes the file of each output kind it was to write, and the
.B \-\-local\-stubs
file, whether or not it wrote them.
Without an option that selects an output kind, that is every default
name except
.IR dlldata.c ,
so a failed run also removes the results of an earlier one.
.SH EXAMPLES
A small IDL file that defines a COM interface:
.PP
.RS 4
.EX
$ cat hello.idl
import "unknwn.idl";
\&
[
object,
uuid(5bb3e1a8\-6f2b\-4d5e\-9c1a\-2f7d3e8b4a10),
pointer_default(unique)
]
interface IHello : IUnknown
{
HRESULT Greet([in, string] const WCHAR *name);
}
.EE
.RE
.PP
Generate its header,
.IR hello.h :
.PP
.RS 4
.EX
$ widl \-h hello.idl
.EE
.RE
.PP
Generate its proxy,
.IR hello_p.c ,
and the interface identifiers that the proxy needs,
.IR hello_i.c :
.PP
.RS 4
.EX
$ widl \-p \-u hello.idl
.EE
.RE
.PP
Generate everything the file calls for:
.IR hello.h ,
.IR hello_i.c ,
.IR hello_p.c ,
.IR hello_r.rgs ,
and
.IR dlldata.c :
.PP
.RS 4
.EX
$ widl hello.idl
.EE
.RE
.PP
Generate a proxy for 32-bit x86:
.PP
.RS 4
.EX
$ widl \-m32 \-p hello.idl
.EE
.RE
.PP
Write the header into another directory:
.PP
.RS 4
.EX
$ widl \-h \-o include/hello.h hello.idl
.EE
.RE
.PP
Compile a type library,
.IR mylib.tlb :
.PP
.RS 4
.EX
$ widl \-t mylib.idl
.EE
.RE
.SH NOTES
The kit also installs
.B widl
under its target-prefixed name, such as
.BR x86_64\-w64\-mingw32\-widl ,
and the 64-bit kit adds
.BR i686\-w64\-mingw32\-widl ,
which passes
.BR \-\-win32 .
Each targets the CPU in its name.
.PP
Default output names are split from
.I file
only at forward slashes.
With a backslash path, such as
.BR src\ehello.idl ,
the outputs go beside the input, as
.IR src\ehello.h ,
the include guard becomes
.BR __src_hello_h__ ,
and imports and quoted includes are looked for in the current directory
instead of in
.IR src .
A name without a lowercase
.B .idl
suffix is kept whole:
.I HELLO.IDL
gives
.IR HELLO.IDL.h .
.PP
Generated C files, headers, registration scripts, and
.B \-E
output end lines with CRLF.
.PP
Paths, including the location of the kit, must be representable in the
ANSI code page and fit in
.B MAX_PATH
characters.
If the kit's own path does not, the standard IDL files are not found.
.PP
Unlike MIDL,
.B widl
does not read an ACF unless given
.BR \-\-acf ,
does not define
.BR __midl ,
and uses
.B \-U
to name a file, not to undefine a macro.
.SH SEE ALSO
.BR cpp (1),
.BR gcc (1),
.BR uuidgen (1),
.BR windres (1)