diff --git a/man/README.md b/man/README.md index 9f3890a..e6cd0db 100644 --- a/man/README.md +++ b/man/README.md @@ -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. diff --git a/man/man1/cmcldeps.1 b/man/man1/cmcldeps.1 new file mode 100644 index 0000000..cc2ec6d --- /dev/null +++ b/man/man1/cmcldeps.1 @@ -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) diff --git a/man/man1/gendef.1 b/man/man1/gendef.1 new file mode 100644 index 0000000..0e454e6 --- /dev/null +++ b/man/man1/gendef.1 @@ -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) diff --git a/man/man1/makensis.1 b/man/man1/makensis.1 new file mode 100644 index 0000000..6596a7c --- /dev/null +++ b/man/man1/makensis.1 @@ -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 +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. diff --git a/man/man1/ninja.1 b/man/man1/ninja.1 new file mode 100644 index 0000000..f699c45 --- /dev/null +++ b/man/man1/ninja.1 @@ -0,0 +1,1144 @@ +.TH NINJA 1 2026-10-20 "w64devkit" "w64devkit Manual" +.SH NAME +ninja \- run the commands of a build file to bring targets up to date +.SH SYNOPSIS +.B ninja +.RI [ options ] +.RI [ target ...] +.br +.B ninja +.RI [ options ] +.B \-t +.I tool +.RI [ argument ...] +.SH DESCRIPTION +.B ninja +reads a build file, +.I build.ninja +unless +.B \-f +names another, which says how to make files from other files, and runs +the commands needed to bring each +.I target +up to date. +It runs several commands at once, but starts a command only after the +commands that make its inputs have finished. +Build files are usually written by a generator such as +.BR cmake (1). +With no +.I target +operands, +.B ninja +builds the targets of the +.B default +statements, or, when there are none, every output that is not an input +of another build statement. +.PP +A +.I target +is a path as written in the build file. +It is canonicalized first: empty and +.B .\& +components are removed, +.IB dir /..\& +is collapsed, and a backslash matches a forward slash. +A +.I target +ending in +.B ^ +means the first output of the first build statement that uses the named +file as an input, such as +.I main.o +for +.IR main.c^ . +.PP +A build statement runs when any of these is true: +.IP \(bu 2 +An output is missing. +.IP \(bu 2 +An output is older than the newest input, ignoring order-only inputs. +.IP \(bu 2 +An output has no entry in the build log, or the logged command differs +from the current one, including the response file contents. +Neither applies to a +.B generator +rule. +.IP \(bu 2 +The time the build log recorded for an output is older than the newest +input. +.IP \(bu 2 +Discovered dependencies are missing or older than the output. +.IP \(bu 2 +An input is itself out of date. +.PP +Before building, if the build file is the output of a build statement, +.B ninja +brings it up to date, and if that changed it, loads it again and starts +over. +After 100 rounds it gives up with an error. +.PP +Progress messages and the output of commands go to standard output, and +diagnostics to standard error, prefixed with +.BR "ninja: error:" , +.BR "ninja: warning:" , +or +.BR "ninja: fatal:" . +.SS Build files +A build file contains these statements, one per line: +.PP +.RS 4 +.EX +\fIname\fR = \fIvalue\fR +rule \fIname\fR +build \fIoutputs\fR [| \fIimplicit\-outputs\fR]: \fIrule\fR [\fIinputs\fR] $ + [| \fIimplicit\-inputs\fR] [|| \fIorder\-only\fR] [|@ \fIvalidations\fR] +default \fItarget\fR ... +pool \fIname\fR +include \fIpath\fR +subninja \fIpath\fR +.EE +.RE +.PP +Lines indented with spaces after a +.BR rule , +.BR build , +or +.B pool +line are +.IB name " = " value +bindings that belong to it. +Tabs are an error. +A line whose first non-space character is +.B # +is a comment; elsewhere +.B # +is an ordinary character. +Lines may end in LF or CR LF. +.PP +.B $ +is the escape character: +.TP +.B $$ +A literal +.BR $ . +.TP +.BR "$ " "(dollar, space)" +A literal space, which would otherwise separate paths. +.TP +.B $: +A literal colon, which would otherwise end the outputs. +.TP +.BR $ " at the end of a line" +Joins the next line, without its leading spaces. +.TP +\fB$\fIname\fR, \fB${\fIname\fB}\fR +The value of a variable. +Names consist of letters, digits, +.BR _ , +and +.BR \- , +and +.B .\& +is also allowed in braces. +.PP +Any other character after +.B $ +is an error. +.PP +A +.B build +statement names at least one output and a rule. +Paths after the outputs' +.B | +are implicit outputs, which are not part of +.BR $out . +Inputs before any +.B | +are explicit, and form +.BR $in . +Implicit inputs, after +.BR | , +are dependencies left out of +.BR $in . +Order-only inputs, after +.BR || , +are built first, but a change to them does not make the statement run. +Validations, after +.BR |@ , +are built whenever the statement is part of a build, but the statement +does not wait for them. +Two statements that make the same output are an error. +.PP +The built-in rule +.B phony +runs no command and makes its output an alias for its inputs. +A +.B phony +statement with no inputs is out of date whenever no file of that name +exists, so everything that depends on it always runs. +.PP +A +.B default +statement adds targets to the default list, and each must be a path +already mentioned earlier in the build file. +A +.B pool +statement needs a +.BI "depth = " count +binding, and limits the statements that select it with +.B pool +to +.I count +commands at once, where 0 means no limit. +The pool +.BR console , +of depth 1, exists already. +Its command inherits +.BR ninja 's +standard input, output, and error, its output is not captured, and the +status line waits until it finishes. +.PP +.B include +reads another file into the current scope. +.B subninja +reads it into a new scope that sees the variables and rules of the +including file, but whose own definitions do not leak back. +Both paths are relative to the current directory, not to the including +file. +A rule name may be defined only once in a scope. +.SS Rules and variables +A +.B rule +statement accepts only these bindings, of which +.B command +is required. +They may also be set on a +.B build +statement. +.TP +.B command +The command line to run. +See +.B NOTES +for how it runs. +.TP +.B depfile +A Makefile-syntax dependency file, such as +.B gcc \-MD +writes, that lists more inputs. +Without +.BR deps , +.B ninja +reads it every time it starts. +The statement is out of date when the file is missing, or when its first +target is not the statement's first output. +A target that is not an output of the statement is an error. +.TP +.B deps +How to save discovered dependencies in the deps log after the command +succeeds. +With +.BR gcc , +.B ninja +reads +.B depfile +and deletes it, and a missing file means no dependencies; +.B depfile +must be set. +With +.BR msvc , +it takes the lines of the command's output that start with +.B msvc_deps_prefix +and removes them from the output. +Each named file is made relative to the current directory when it is on +the same drive, and is dropped when its path contains +.B program files +or +.BR "microsoft visual studio" , +in any case. +Before the first such line, a line ending in +.BR .c , +.BR .cc , +.BR .cxx , +.BR .cpp , +or +.BR .c++ , +which +.B cl +prints, is also removed. +Any other value makes +.B ninja +stop with a fatal error after the command runs. +.TP +.B msvc_deps_prefix +The prefix of include lines for +.BR "deps = msvc" . +The default is +.B Note: including file: +followed by a space. +.TP +.B description +Shown in the status line instead of the command, except with +.BR \-v . +.TP +.B dyndep +A file, which must be one of the statement's inputs, that lists more +implicit inputs and outputs. +.B ninja +reads it as soon as it is up to date. +Its first statement must set +.B ninja_dyndep_version +to 1, and each build statement that names the file needs a statement +\fBbuild\fR \fIoutput\fR [\fB|\fR \fIoutputs\fR]\fB: dyndep\fR +[\fB|\fR \fIinputs\fR] +in it, where +.I output +is one of the statement's outputs, optionally followed by an indented +.B restat +binding. +.TP +.B generator +Marks a rule that generates the build file: its outputs are not rebuilt +when the command changes, and +.B "\-t clean" +keeps them unless given +.BR \-g . +.TP +.B pool +The pool the statement belongs to. +An unknown pool is an error. +.TP +.B restat +After the command succeeds, check the outputs again, and treat any +output whose time did not change as up to date, so that statements +that depend only on it do not run. +.TP +.B rspfile +A response file to write before the command runs, deleted after the +command succeeds and kept when it fails. +It must be set together with +.BR rspfile_content . +.TP +.B rspfile_content +The text of +.BR rspfile . +.PP +Any non-empty value of +.B generator +or +.BR restat , +even +.BR 0 , +means true. +.PP +In a rule, these variables are also defined: +.TP +.B $in +The explicit inputs, separated by spaces. +.TP +.B $in_newline +The explicit inputs, separated by newlines. +.TP +.B $out +The explicit outputs, separated by spaces. +.PP +Each path in these is canonicalized but keeps its backslashes, and is +enclosed in double quotes when it contains a space or a double quote. +Inside the quotes, a double quote and the backslashes before it are +escaped with backslashes, as the Microsoft C runtime expects. +.PP +Two variables of the top file's scope have a meaning: +.TP +.B builddir +The directory for the log files, created when needed. +.TP +.B ninja_required_version +.B ninja +stops with a fatal error when this version is newer than 1.13, +comparing the major and minor numbers, and warns when its major number +is 0. +.PP +The value of a file-level variable, or of a binding on a +.B build +statement, is expanded once when it is read. +A +.B build +statement's bindings are expanded in the file's scope, so they cannot +use +.BR $in , +.BR $out , +or each other. +Rule bindings are expanded when they are used, looking up each variable +in this order: +.BR $in , +.BR $in_newline , +and +.BR $out ; +the +.B build +statement's bindings; the rule's bindings; the file's variables; and the +variables of the files that include it with +.BR subninja . +File variables are looked up when the command runs, so a rule sees the +last value assigned in the file, even after the +.B build +statement. +For a +.B build +statement with no bindings of its own, the file's variables are looked +up before the rule's: a file-level +.B description +or +.B restat +overrides the rule's for such statements. +Rule bindings that refer to each other in a cycle are a fatal error. +.SS Status output +Each command is announced by a status line: the expansion of +.BR NINJA_STATUS , +followed by the +.B description +or, when there is none or with +.BR \-v , +the command. +When standard output is a console, +.B TERM +is not +.BR dumb , +and neither +.B \-v +nor +.B \-\-quiet +is given, the status line is shown as commands start and finish, +overwritten in place, and shortened in the middle to the console width. +Otherwise one line is printed as each command finishes. +.PP +Each command's output is printed after its status line when the command +finishes, never mixed with other output. +A command that fails is reported as +.PP +.RS 4 +.EX +FAILED: [code=\fIstatus\fR] \fIoutput\fR ... +\fIcommand\fR +.EE +.RE +.PP +followed by its output. +When nothing needs to run, +.B ninja +says there is no work to do, and when a build stops early, it says so +and why. +.SS Files +These are in the directory named by +.BR builddir , +or in the current directory. +.TP +.I .ninja_log +The build log: for each output, a hash of its command, the command's +start and end times, and the output's time. +.TP +.I .ninja_deps +The deps log, a binary file of discovered dependencies. +.TP +.I .ninja_lock +An empty file written as commands start, to read the file system's +time, and removed afterwards. +.PP +Both logs are rewritten without stale entries when they hold many. +A log of another version is deleted with a warning, and a damaged deps +log is truncated after its last good record. +.SS Tools +.B \-t +runs a tool instead of a build. +Except for +.BR msvc , +.BR restat , +.BR urtle , +and +.BR wincodepage , +tools load the build file first, without regenerating it. +Unless noted, tools that take +.I target +operands use the default targets when there are none. +For +.BR \-h , +the tools that have options print their usage on standard output and +exit with status 1, except +.BR msvc , +which exits with status 0. +Other tools take +.B \-h +as an operand, and +.BR cleandead , +.BR recompact , +and +.B urtle +ignore their operands. +.TP +.B browse +Not available on Windows: stops with a fatal error. +.TP +\fBmsvc\fR [\fB\-e\fR \fIenvfile\fR] [\fB\-o\fR \fIfile\fR] \ +[\fB\-p\fR \fIprefix\fR] \fB\-\-\fR \fIcommand\fR +Deprecated. +Run +.IR command , +then copy its standard output to standard output and exit with its +status. +Its standard error is not captured. +.I command +is the text after the first +.B \-\- +with a space on each side in +.BR ninja 's +own command line. +.B \-e +reads a Windows environment block, NUL-separated +.IB name = value +strings, from +.I envfile +for the command, and also takes +.B PATH +from it. +.B \-o +removes include lines from the output, as +.B "deps = msvc" +does, with +.B \-p +as the prefix, and writes +.IB file .d\fR: +.IR file , +a colon, and a space, then the included files one per line, which is +not a valid depfile when there is more than one. +In this build, +.B \-o +never finishes if any output line remains after the removal, even an +empty one or a compiler warning: memory use grows until it fails. +.TP +\fBclean\fR [\fB\-gr\fR] [\fItarget\fR ...] +Delete the outputs of every statement, except +.B phony +statements and +.B generator +rules, with their depfiles and response files, and print the count. +With +.I target +operands, delete those targets and every built file they depend on, +including generator outputs. +.B \-g +also deletes generator outputs. +.B \-r +takes rule names instead of targets, and deletes the outputs of their +statements. +Read-only files are deleted too. +Given +.B \-n +before +.BR \-t , +nothing is deleted, and given +.B \-n +or +.BR \-v , +each file is listed. +The exit status is 1 if a file could not be deleted or an operand is +unknown. +.TP +\fBcommands\fR [\fB\-s\fR] [\fItarget\fR ...] +Print the commands that build the targets, each after the commands it +depends on. +.B \-s +prints only the command of the statement that makes each target. +.TP +\fBinputs\fR [\fB\-0dE\fR] [\fItarget\fR ...] +Print every input needed to build the targets, directly or indirectly, +except outputs of +.B phony +statements, one per line, sorted, and quoted as for +.BR $in . +.BR \-0 " or " \-\-print0 +ends each path with a NUL instead. +.BR \-d " or " \-\-dependency\-order +does not sort. +.BR \-E " or " \-\-no\-shell\-escape +does not quote. +.TP +\fBmulti\-inputs\fR [\fB\-0\fR] [\fB\-d\fR \fIdelim\fR] [\fItarget\fR ...] +Like +.BR inputs , +unsorted and unquoted, but print each input as the target, a tab, and +the input. +.BR \-d " or " \-\-delimiter +replaces the tab with +.IR delim , +and +.BR \-0 " or " \-\-print0 +ends each line with a NUL. +.TP +\fBdeps\fR [\fItarget\fR ...] +Print the dependencies stored in the deps log, by default for every +output that is still built with +.BR deps . +Each entry is the output, the dependency count, the recorded time, +.B VALID +or +.BR STALE , +and the dependencies, indented. +.TP +\fBmissingdeps\fR [\fItarget\fR ...] +Report each discovered dependency on a generated file that has no path +to its generator in the build graph, so that the target may build before +the file exists. +Exits with status 3 if there are any. +.TP +\fBgraph\fR [\fItarget\fR ...] +Print the dependency graph of the targets for Graphviz +.BR dot . +.TP +\fBquery\fR \fItarget\fR ... +Print each target's rule and inputs, with implicit inputs marked +.B | +and order-only inputs +.BR || , +the outputs of the statements that use it, and any validations. +.TP +\fBtargets\fR [\fBdepth\fR [\fIn\fR] | \fBrule\fR [\fIname\fR] | \fBall\fR] +Print targets and their rules. +.B depth +starts from the outputs that are not inputs and shows their inputs +indented, to +.I n +levels, 1 by default, and without limit when +.I n +is 0 or less. +.BI "rule " name +prints the outputs of rule +.I name +sorted, and +.B rule +alone prints every input that no statement makes, once per use. +.B all +prints every output. +The default is +.BR "depth 1" . +.TP +\fBcompdb\fR [\fB\-x\fR] [\fIrule\fR ...] +Print a JSON compilation database of every statement with inputs, or only +of those using the named rules, giving each one's directory, command, +first input, and first output. +Without +.I rule +operands, +.B phony +statements are included, with empty commands. +.B \-x +replaces a response file named in the command after +.BR @ , +after +.B \-f +and a space, or after +.B \-\-option\-file= +with its contents, with newlines turned into spaces. +.TP +\fBcompdb\-targets\fR [\fB\-x\fR] \fItarget\fR ... +Like +.BR compdb , +but for the statements, except +.B phony +ones, needed to build the targets, each of which must be an output. +.TP +.B recompact +Rewrite the logs without stale entries. +.TP +\fBrestat\fR [\fIoutput\fR ...] +Record the current time of each output, or of every output, in the build +log. +It uses +.I .ninja_log +in the current directory, ignoring +.BR builddir . +.TP +\fBrules\fR [\fB\-d\fR] +Print the names of the rules of the top file's scope, which includes +files read with +.B include +but not with +.BR subninja , +sorted. +.B \-d +adds each description, unexpanded. +.TP +.B cleandead +Delete the files that the build log lists but the build file no longer +mentions. +.TP +.B urtle +Print a turtle. +It is not listed by +.BR "\-t list" . +.TP +.B wincodepage +Print +.B "Build file encoding: UTF\-8" +if the Windows ANSI code page is UTF-8, and +.B "Build file encoding: ANSI" +otherwise. +.TP +.B list +Print the tools and exit. +.SH OPTIONS +Options may follow targets, unless +.B POSIXLY_CORRECT +is set. +Options without arguments may be grouped, as in +.BR \-nv . +An option's argument may be attached, as in +.BR \-j4 , +or be the next argument, and an attached argument loses one leading +.BR = , +so +.B \-j=4 +is +.BR \-j4 . +Long options may be abbreviated to any unique prefix. +.B \-\- +ends the options. +.B \-t +ends +.BR ninja 's +options, and the remaining arguments go to the tool, which parses its +own options the same way. +.TP +.B \-\-version +Print the version, 1.13.2, and exit. +.TP +.BR \-v ", " \-\-verbose +Show full commands instead of descriptions, and print status lines +without overwriting them. +.TP +.B \-\-quiet +Print no status lines, and none of the +.BR "no work to do" , +.BR "Entering directory" , +and +.B Jobserver mode detected +messages. +Command output and failures are still printed. +.TP +.BI "\-C " dir +Change to +.I dir +before doing anything else, and print +\fBninja: Entering directory \(ga\fIdir\fB\(aq\fR +unless running a tool. +.TP +.BI "\-f " file +Read +.I file +instead of +.IR build.ninja . +.TP +.BI "\-j " n +Run up to +.I n +commands at once, where 0 means no limit. +.I n +must be a decimal integer. +The default is the number of logical processors plus 2, or 2 with one +processor and 3 with two, where a CPU rate limit on the process's job +reduces the count of processors. +.B \-j +turns off the +.B MAKEFLAGS +jobserver. +.TP +.BI "\-k " n +Keep going until +.I n +commands have failed, where 0 or less means no limit. +The default is 1. +After that, no new commands start, but running commands finish. +.TP +.BI "\-l " load +Start no more new commands at a time than +.I load +minus the current load average, rounded down, but always one when none +is running. +A +.I load +of 0 or less, the default, means no limit. +The load average is estimated: the busy fraction of all processors since +the previous check, smoothed, times the number of processors. +.TP +.B \-n +Dry run: act as if every command ran and succeeded, without running it. +Output directories are still created, and response files are still +written and deleted. +The logs are not updated. +If the build file would be regenerated, +.B ninja +exits with status 0 after that step. +.B \-n +turns off the +.B MAKEFLAGS +jobserver. +.TP +.BI "\-d " mode +Turn on a debugging mode. +.B \-d +may be repeated. +.RS +.TP +.B stats +After a build, print operation counts and times on standard output. +.TP +.B explain +Print on standard error why each command runs. +.TP +.B keepdepfile +Keep depfiles after reading them for +.BR "deps = gcc" . +.TP +.B keeprsp +Keep response files after their commands succeed. +.TP +.B nostatcache +Check the time of each file separately, instead of reading each +directory once. +.TP +.B list +Print the modes and exit. +.RE +.TP +.BI "\-t " tool +Run +.I tool +instead of building; see +.BR Tools . +.TP +.BI "\-w " flag +Adjust a warning. +.RS +.TP +.B phonycycle=err +A +.B phony +statement with one output and no implicit inputs or outputs that lists +its output as an input is a dependency cycle. +.TP +.B phonycycle=warn +Remove such an input with a warning. +This is the default. +.TP +\fBdupbuild=\fR{\fBerr\fR,\fBwarn\fR}, \fBdepfilemulti=\fR{\fBerr\fR,\fBwarn\fR} +Ignored, with a warning that they are deprecated. +.TP +.B list +Print the flags and exit. +.RE +.TP +.BR \-h ", " \-\-help +Print a usage message on standard error and exit. +.SH ENVIRONMENT +.TP +.B CLICOLOR_FORCE +When set to anything but +.BR 0 , +turn on color even when standard output is not a console that supports +it: color escape sequences in command output are kept instead of +removed, and +.B FAILED +is shown in red. +.TP +.B MAKEFLAGS +When it contains +.BI \-\-jobserver\-auth= name\fR, +as GNU make sets it for recursive commands, +.B ninja +limits the commands it runs at once by taking a token from the Windows +semaphore +.I name +for each command after the first, instead of by the default +.B \-j +limit. +The pipe and +.B fifo: +forms, and +.BR \-\-jobserver\-fds , +are ignored with a warning, and a semaphore that cannot be opened with +an error. +.B MAKEFLAGS +is ignored with +.B \-j +or +.BR \-n , +or when its first word does not start with +.B \- +and contains +.BR n . +.TP +.B NINJA_STATUS +The format of the status line prefix, by default +.B [%f/%t] +followed by a space. +These placeholders are replaced: +.RS +.TP +.B %s +Commands started. +.TP +.B %t +Commands to run in total. +.TP +.B %r +Commands running. +.TP +.B %u +Commands not yet started. +.TP +.B %f +Commands finished. +.TP +.B %o +Commands finished per second, over the whole build. +.TP +.B %c +Commands finished per second, over the last +.B \-j +commands, or +.B ?\& +until known. +.TP +.B %p +Percentage of commands finished. +.TP +.B %e +Seconds elapsed, with 3 decimals. +.TP +.B %w +Time elapsed, as +.IB mm : ss +or +.IB h : mm : ss\fR. +.TP +.BR %E ", " %W +Estimated time remaining, as for +.B %e +and +.BR %w , +based on the times in the build log, or +.B ?\& +until known. +.TP +.B %P +Estimated percentage of the total time elapsed so far. +.TP +.B %% +A literal +.BR % . +.RE +.IP +Any other placeholder, or a +.B % +at the end, is a fatal error when the first status line is printed. +.TP +.B PATH +Searched for a command's program, after +.BR ninja 's +own directory, the current directory, and the Windows system +directories. +.TP +.B POSIXLY_CORRECT +When set, options end at the first argument that is not an option, +both for +.B ninja +and for its tools. +.TP +.B TERM +When +.BR dumb , +the status line is not overwritten in place, and color is off. +.SH EXIT STATUS +.TP +.B 0 +Success, including +.BR \-\-version , +.BR "\-t list" , +and most tools. +.TP +.B 1 +An error: an invalid option or build file, an unknown target, a fatal +error, +.BR \-h , +.BR "\-d list" , +or +.BR "\-w list" . +.TP +.B 3 +.B "\-t missingdeps" +found missing dependencies. +.TP +.B 130 +The build was interrupted with Ctrl-C or Ctrl-Break, or a command exited +with +.BR STATUS_CONTROL_C_EXIT . +.PP +When commands fail, +.B ninja +exits with the status of the last one that failed, which may be any +value, and is 1 when the program was not found. +.SH EXAMPLES +A build file that compiles and links a C program with +.BR gcc , +recording each object's headers in the deps log: +.PP +.RS 4 +.EX +cflags = \-O2 \-Wall +rule cc + command = gcc \-MMD \-MF $out.d $cflags \-c \-o $out $in + deps = gcc + depfile = $out.d + description = CC $out +rule link + command = gcc \-o $out $in + description = LINK $out +build main.o: cc main.c +build util.o: cc util.c +build app.exe: link main.o util.o +.EE +.RE +.PP +Build it with four commands at once: +.PP +.RS 4 +.EX +$ ninja \-j4 +.EE +.RE +.PP +Show why commands would run, without running them: +.PP +.RS 4 +.EX +$ ninja \-n \-d explain +.EE +.RE +.PP +Show the command that builds one file: +.PP +.RS 4 +.EX +$ ninja \-t commands \-s util.o +gcc \-MMD \-MF util.o.d \-O2 \-Wall \-c \-o util.o util.c +.EE +.RE +.PP +Show where a file fits in the graph: +.PP +.RS 4 +.EX +$ ninja \-t query main.o +main.o: + input: cc + main.c + outputs: + app.exe +.EE +.RE +.PP +Write a compilation database for the C sources: +.PP +.RS 4 +.EX +$ ninja \-t compdb cc >compile_commands.json +.EE +.RE +.PP +List the files that cleaning would delete, then delete them: +.PP +.RS 4 +.EX +$ ninja \-n \-t clean +$ ninja \-t clean +.EE +.RE +.PP +Build in the directory +.I build +with the percentage done and the elapsed time in the status line: +.PP +.RS 4 +.EX +$ NINJA_STATUS=\(aq[%p %w] \(aq ninja \-C build +.EE +.RE +.SH NOTES +Commands are started with +.BR CreateProcess , +not through a shell, so redirection, pipes, and other shell syntax need +.B "cmd /c" +or +.BR "sh \-c" . +.B CreateProcess +looks for the program in +.BR ninja 's +own directory, which is the kit's +.IR bin , +the current directory, and the Windows system directories before +.BR PATH . +A command whose program is not found fails with the output +.PP +.RS 4 +.EX +CreateProcess failed: The system cannot find the file specified. +.EE +.RE +.PP +but when other commands run at the same time or later, +.B ninja +may instead stop with a fatal error from +.BR ReadFile . +Any other failure to start a command, such as a command line longer than +32767 characters, is a fatal error, so use a response file for long +lists. +.PP +Commands outside the +.B console +pool get the null device as standard input, and one pipe for both +standard output and standard error, so they do not see a console and +often turn off color unless told otherwise. +They run in their own process group. +On Ctrl-C or Ctrl-Break, +.B ninja +sends Ctrl-Break to each of them, deletes the outputs that the +interrupted commands changed, or all their outputs and the depfile when +the rule has a depfile, and exits with status 130. +.PP +This build of +.B ninja +has no application manifest, so it uses the ANSI code page: paths in the +build file, in depfiles, and in +.I target +operands are in that code page, which is UTF-8 only when Windows is set +to use UTF-8 for it. +A path longer than 260 characters that does not start with a backslash +fails with +.BR "Filename longer than 260 characters" . +.PP +Paths are compared byte for byte, so +.I foo.c +and +.I Foo.c +are different targets even when they name the same file. +File times have a resolution of 100 nanoseconds. +Response files are written in text mode, so each line ends in CR LF. +.PP +The kit patches +.B ninja +so that recovery from a damaged deps log removes the damaged record. +Upstream Ninja 1.13.2 can keep it, and then rebuilds on every run. +.SH SEE ALSO +.BR cmake (1), +.BR cmcldeps (1), +.BR gcc (1), +.BR make (1) diff --git a/man/man1/widl.1 b/man/man1/widl.1 new file mode 100644 index 0000000..133a957 --- /dev/null +++ b/man/man1/widl.1 @@ -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)