3 # CrossReport - analysis tool.
4 # Copyright (C) 2009 Red Hat Inc.
5 # Written by Richard W.M. Jones <rjones@redhat.com>,
6 # http://fedoraproject.org/wiki/MinGW
8 # This program is free software; you can redistribute it and/or modify
9 # it under the terms of the GNU General Public License as published by
10 # the Free Software Foundation; either version 2 of the License, or (at
11 # your option) any later version.
13 # This program is distributed in the hope that it will be useful, but
14 # WITHOUT ANY WARRANTY; without even the implied warranty of
15 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 # General Public License for more details.
18 # You should have received a copy of the GNU General Public License
19 # along with this program; if not, write to the Free Software
20 # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
27 use POSIX qw(strftime floor);
33 CrossReport - Analysis tool to help cross-compilation to Windows.
37 mingw32-crossreport [options] /path/to/linuxbinary
41 CrossReport is a tool to help you analyze the APIs used by a compiled
42 Linux program, in order to work out the effort required to
43 cross-compile that program for Windows, using the Fedora MinGW
46 The simplest way to use it is to point it at an existing Linux binary,
47 and then read the generated report.
49 What it does in more detail: It looks at the libraries and API calls
50 used by the Linux binary, and compares them to the libraries and API
51 calls that we currently support under the Fedora MinGW cross-compiler.
52 It then works out what is missing, and produces a report suggesting
53 the amount of work that needs to be done to port the program. For
54 example, whether whole libraries need to be ported first, and/or how
55 to substitute individual calls to work on Windows.
59 Assuming that the excellent vector graphics editor Inkscape
60 (L<http://www.inkscape.org/>) is installed, you could do:
62 mingw32-crossreport /usr/bin/inkscape > inkscape-report.txt
63 less inkscape-report.txt
67 The report is only a general guide. CrossReport contains a lot of
68 knowledge about common Linux calls and APIs, but does not know about
69 every possible library.
73 The program relies on a database of MinGW APIs. The default location
74 for this database is C</usr/share/crossreport/crossreport.db> or the
75 same file in the current working directory. If the database cannot be
76 found in either location, the program will fail with an error message.
78 The database is updated regularly and distributed with CrossReport.
79 To get the best quality report, make sure you are running a recent
80 version of the program.
91 my $result = GetOptions (
94 "verbose" => \$verbose,
96 die "crossreport: use --help for information about command line options\n"
99 pod2usage(1) if $help;
100 pod2usage(-exitstatus => 0, -verbose => 2) if $man;
102 die "crossreport: no binary specified: use --help for more help\n"
112 foreach ("/usr/local/share/crossreport/crossreport.db",
113 "/usr/share/crossreport/crossreport.db",
116 tie %symbols, "GDBM_File", $_, &GDBM_READER, 0;
120 die "Could not find crossreport.db\n"
123 # Get the symbols (API calls) used by the binary.
125 my %api = (); # Count how each API is used.
126 my @unresolved = (); # List of unresolved symbols.
130 my $cmd = "nm -D $binary | grep ' U ' | awk '{print \$2}' | c++filt";
131 open CMD, "$cmd |" or die "$cmd: $!";
134 if (exists $symbols{$_}) {
135 my $rpm_name = $symbols{$_};
136 $api{$rpm_name} = 0 unless exists $api{$rpm_name};
139 push @unresolved, $_;
145 #----------------------------------------------------------------------
148 # This hash contains our area expertise about some unresolved symbols.
150 my $suggest_portability_library =
151 "To get more reliable semantics, we suggest you use a portability\n".
152 "library such as Gnulib, glib2, QtCore, etc.\n";
153 my $warning_about_read_write_on_sockets =
154 "If you are using read/write on sockets, then this won't work on\n".
155 "Windows. You should use recv/send instead.\n";
159 "Program uses POSIX open/close/read/write/... APIs. You should be\n".
160 "aware that Win32 provides functions with the same name which do not\n".
161 "have POSIX semantics. Simple file operations will be fine, but you\n".
162 "will not be able to, for example, open /dev/* or other special files,\n".
163 "and select, locking and other POSIX features will not work the same\n".
166 "$suggest_portability_library".
168 "$warning_about_read_write_on_sockets",
174 "Program uses Berkeley sockets API. Windows has a reasonable facsimile\n".
175 "called Winsock. However it has some annoying API differences, in\n".
176 "particular: (1) You have to use WSAGetLastError instead of errno,\n".
177 "(2) error numbers have different names, (3) you cannot select on,\n".
178 "sockets, (4) a multitude of small API differences, (5) you have to\n".
179 "initialize Winsock before using it by calling WSAStartup.\n".
181 "$suggest_portability_library".
183 "$warning_about_read_write_on_sockets",
184 "socketpair" => '@socket',
185 "accept" => '@socket',
187 "connect" => '@socket',
188 "listen" => '@socket',
189 "getsockopt" => '@socket',
190 "setsockopt" => '@socket',
191 "shutdown" => '@socket',
194 "Program uses fcntl or ioctl system calls. Only a tiny fraction of\n".
195 "the functionality of these system calls is available in Windows,\n".
196 "often with differences in semantics.\n".
198 "$suggest_portability_library",
202 "The select/poll/etc system calls are not available on Windows. You\n".
203 "have to use WSAWaitForMultipleEvents instead.\n".
205 "$suggest_portability_library",
207 "epoll_create" => '@select',
208 "epoll_ctl" => '@select',
209 "epoll_wait" => '@select',
212 "You cannot use fork to create new processes under Windows. You have\n".
213 "to replace calls to fork/exec with CreateProcess or CreateThread.\n".
215 "If your program forks in order to run in parallel or to create\n".
216 "multiple identical workers, then you may have to restructure the\n".
219 "If your program needs to share resources such as file descriptors\n".
220 "across the fork, then some limited options are available through\n".
221 "CreateProcess, but nothing like as rich as what is available in\n".
224 "For server programs, we suggest using a portability library tuned\n".
225 "for the needs of servers, such as Apache Portable Runtime.\n",
234 "usleep/nanosleep system calls do not exist on Windows. You should\n".
235 "replace this with one of the Win32 equivalents such as Sleep.\n".
237 "$suggest_portability_library",
238 "nanosleep" => '@usleep',
241 "dup/dup2 may not work as expected in Win32.\n".
243 "$suggest_portability_library",
247 "GNU getopt_long is not available in Windows.\n".
249 "$suggest_portability_library",
251 "__stack_chk_fail" =>
252 "The -fstack-protector option may not work with the Fedora MinGW\n".
253 "cross-compiler at this time.\n",
256 # List of symbols for which there is no known problem.
259 __libc_start_main => 1,
274 my $date = strftime "%a %b %e %H:%M:%S %Y", localtime ($time);
275 my $sym_time = $symbols{__crossreport_time};
276 my $sym_date = strftime "%a %b %e %H:%M:%S %Y", localtime ($sym_time);
277 my $days = floor (($time - $sym_time) / 86400);
280 Cross-compilation report for: $binary
282 Report prepared on $date.
283 Symbol database last updated on $sym_date ($days days ago).
288 # Report resolved libraries.
293 This table shows the supported APIs that this program uses,
294 including the number of different calls made to each API.
295 In most cases, you just need to arrange it so that your program
296 'BuildRequires' these RPMs and links to the libraries within them.
301 foreach (sort (keys %api)) {
302 printf " %10d %s\n", $api{$_}, $_;
308 # Report unresolved symbols.
310 sub report_unresolved
312 @unresolved = sort @unresolved;
314 if (0 == @unresolved) {
316 No unresolved symbols were found. Programs which have no
317 unresolved symbols at all are the easiest to port because
318 portability libraries (eg. glib, Qt) have already done all
319 the hard work for you.
322 my $nr_unresolved = @unresolved;
324 $nr_unresolved unresolved symbols were found. The full list of symbols
325 is listed as an appendix at the end of this report. In this
326 section we try to identify known portability problems from
327 this list of symbols.
331 foreach (@unresolved) {
332 if (!exists $no_report{$_}) {
333 if (exists $report{$_}) {
335 $r = $report{$1} while $r =~ /@(.*)/;
336 print "Program uses: $_\n\n$r\n";
343 Appendix - Full list of unresolved symbols
345 * = Symbol we were not able to give advice about. If you know
346 more about this symbol, consider providing a patch for the
349 ✓ = Win32 should supply this symbol, or it can be ignored because
350 it is a side-effect of the Unix toolchain.
354 foreach (@unresolved) {
356 exists $no_report{$_} ? "✓" :
357 (exists $report{$_} ? " " : "*");
372 report_unresolved ();
381 Copyright (C) 2009 Red Hat Inc.
382 Written by Richard W.M. Jones <rjones@redhat.com>.
384 This program is free software; you can redistribute it and/or modify
385 it under the terms of the GNU General Public License as published by
386 the Free Software Foundation; either version 2 of the License, or (at
387 your option) any later version.
389 This program is distributed in the hope that it will be useful, but
390 WITHOUT ANY WARRANTY; without even the implied warranty of
391 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
392 General Public License for more details.
394 You should have received a copy of the GNU General Public License
395 along with this program; if not, write to the Free Software
396 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.