diff --git a/.gitignore b/.gitignore index 6f6d359..e0229ff 100644 --- a/.gitignore +++ b/.gitignore @@ -1,14 +1,17 @@ -build -build.bat -run.bat -clean.bat -work -.vscode -.ds_store - -GPATH -GRTAGS -GTAGS -/run_release.bat -/package.bat -pkg \ No newline at end of file +build +build_rel +build.bat +run.bat +clean.bat +work +.vscode +.ds_store + +GPATH +GRTAGS +GTAGS +/run_release.bat +/package.bat +pkg +pkg.zip +eco2d.zip \ No newline at end of file diff --git a/run_client.bat b/run_client.bat index 8f7acca..a4387b1 100644 --- a/run_client.bat +++ b/run_client.bat @@ -1,3 +1,4 @@ @echo off -build\Debug\eco2d.exe -v %* +call build.bat +build\eco2d.exe -v %* diff --git a/screenshot000.png b/screenshot000.png deleted file mode 100644 index 157d614..0000000 Binary files a/screenshot000.png and /dev/null differ diff --git a/tools/7zCon.sfx b/tools/7zCon.sfx new file mode 100644 index 0000000..fa17a73 Binary files /dev/null and b/tools/7zCon.sfx differ diff --git a/tools/7zSD.sfx b/tools/7zSD.sfx new file mode 100644 index 0000000..c4a710b Binary files /dev/null and b/tools/7zSD.sfx differ diff --git a/tools/7za.dll b/tools/7za.dll new file mode 100644 index 0000000..bc2b47a Binary files /dev/null and b/tools/7za.dll differ diff --git a/tools/7za.exe b/tools/7za.exe new file mode 100644 index 0000000..9f27b20 Binary files /dev/null and b/tools/7za.exe differ diff --git a/tools/7zxa.dll b/tools/7zxa.dll new file mode 100644 index 0000000..d51e3f0 Binary files /dev/null and b/tools/7zxa.dll differ diff --git a/tools/COPYING b/tools/COPYING new file mode 100644 index 0000000..d159169 --- /dev/null +++ b/tools/COPYING @@ -0,0 +1,339 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Lesser General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License along + with this program; if not, write to the Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. diff --git a/tools/License.txt b/tools/License.txt new file mode 100644 index 0000000..e5d33d7 --- /dev/null +++ b/tools/License.txt @@ -0,0 +1,31 @@ + 7-Zip Extra + ~~~~~~~~~~~ + License for use and distribution + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Copyright (C) 1999-2019 Igor Pavlov. + + 7-Zip Extra files are under the GNU LGPL license. + + + Notes: + You can use 7-Zip Extra on any computer, including a computer in a commercial + organization. You don't need to register or pay for 7-Zip. + + + GNU LGPL information + -------------------- + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Lesser General Public + License as published by the Free Software Foundation; either + version 2.1 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Lesser General Public License for more details. + + You can receive a copy of the GNU Lesser General Public License from + http://www.gnu.org/ + diff --git a/tools/config.txt b/tools/config.txt new file mode 100644 index 0000000..646cb76 --- /dev/null +++ b/tools/config.txt @@ -0,0 +1,4 @@ +;!@Install@!UTF-8! +Title="eco2d" +RunProgram="eco2d.exe" +;!@InstallEnd@! \ No newline at end of file diff --git a/tools/upx.1 b/tools/upx.1 new file mode 100644 index 0000000..4416a38 --- /dev/null +++ b/tools/upx.1 @@ -0,0 +1,1046 @@ +.\" Automatically generated by Pod::Man 4.12 (Pod::Simple 3.39) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "UPX 1" +.TH UPX 1 "2020-01-23" "upx 3.96" " " +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +upx \- compress or expand executable files +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +\&\fBupx\fR [\ \fIcommand\fR\ ] [\ \fIoptions\fR\ ] \fIfilename\fR... +.SH "ABSTRACT" +.IX Header "ABSTRACT" +.Vb 3 +\& The Ultimate Packer for eXecutables +\& Copyright (c) 1996\-2020 Markus Oberhumer, Laszlo Molnar & John Reiser +\& https://upx.github.io +.Ve +.PP +\&\fB\s-1UPX\s0\fR is a portable, extendable, high-performance executable packer for +several different executable formats. It achieves an excellent compression +ratio and offers \fI*very*\fR fast decompression. Your executables suffer +no memory overhead or other drawbacks for most of the formats supported, +because of in-place decompression. +.PP +While you may use \fB\s-1UPX\s0\fR freely for both non-commercial and commercial +executables (for details see the file \s-1LICENSE\s0), we would highly +appreciate if you credit \fB\s-1UPX\s0\fR and ourselves in the documentation, +possibly including a reference to the \fB\s-1UPX\s0\fR home page. Thanks. +.PP +[ Using \fB\s-1UPX\s0\fR in non-OpenSource applications without proper credits +is considered not politically correct ;\-) ] +.SH "DISCLAIMER" +.IX Header "DISCLAIMER" +\&\fB\s-1UPX\s0\fR comes with \s-1ABSOLUTELY NO WARRANTY\s0; for details see the file \s-1LICENSE.\s0 +.PP +This is the first production quality release, and we plan that future 1.xx +releases will be backward compatible with this version. +.PP +Please report all problems or suggestions to the authors. Thanks. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fB\s-1UPX\s0\fR is a versatile executable packer with the following features: +.PP +.Vb 2 +\& \- excellent compression ratio: compresses better than zip/gzip, +\& use UPX to decrease the size of your distribution ! +\& +\& \- very fast decompression: about 10 MiB/sec on an ancient Pentium 133, +\& about 200 MiB/sec on an Athlon XP 2000+. +\& +\& \- no memory overhead for your compressed executables for most of the +\& supported formats +\& +\& \- safe: you can list, test and unpack your executables +\& Also, a checksum of both the compressed and uncompressed file is +\& maintained internally. +\& +\& \- universal: UPX can pack a number of executable formats: +\& * atari/tos +\& * bvmlinuz/386 [bootable Linux kernel] +\& * djgpp2/coff +\& * dos/com +\& * dos/exe +\& * dos/sys +\& * linux/386 +\& * linux/elf386 +\& * linux/sh386 +\& * ps1/exe +\& * rtm32/pe +\& * tmt/adam +\& * vmlinuz/386 [bootable Linux kernel] +\& * vmlinux/386 +\& * watcom/le (supporting DOS4G, PMODE/W, DOS32a and CauseWay) +\& * win32/pe (exe and dll) +\& * win64/pe (exe and dll) +\& * arm/pe (exe and dll) +\& * linux/elfamd64 +\& * linux/elfppc32 +\& * mach/elfppc32 +\& +\& \- portable: UPX is written in portable endian\-neutral C++ +\& +\& \- extendable: because of the class layout it\*(Aqs very easy to support +\& new executable formats or add new compression algorithms +\& +\& \- free: UPX can be distributed and used freely. And from version 0.99 +\& the full source code of UPX is released under the GNU General Public +\& License (GPL) ! +.Ve +.PP +You probably understand now why we call \fB\s-1UPX\s0\fR the "\fIultimate\fR" +executable packer. +.SH "COMMANDS" +.IX Header "COMMANDS" +.SS "Compress" +.IX Subsection "Compress" +This is the default operation, eg. \fBupx yourfile.exe\fR will compress the file +specified on the command line. +.SS "Decompress" +.IX Subsection "Decompress" +All \fB\s-1UPX\s0\fR supported file formats can be unpacked using the \fB\-d\fR switch, eg. +\&\fBupx \-d yourfile.exe\fR will uncompress the file you've just compressed. +.SS "Test" +.IX Subsection "Test" +The \fB\-t\fR command tests the integrity of the compressed and uncompressed +data, eg. \fBupx \-t yourfile.exe\fR check whether your file can be safely +decompressed. Note, that this command doesn't check the whole file, only +the part that will be uncompressed during program execution. This means +that you should not use this command instead of a virus checker. +.SS "List" +.IX Subsection "List" +The \fB\-l\fR command prints out some information about the compressed files +specified on the command line as parameters, eg \fBupx \-l yourfile.exe\fR +shows the compressed / uncompressed size and the compression ratio of +\&\fIyourfile.exe\fR. +.SH "OPTIONS" +.IX Header "OPTIONS" +\&\fB\-q\fR: be quiet, suppress warnings +.PP +\&\fB\-q \-q\fR (or \fB\-qq\fR): be very quiet, suppress errors +.PP +\&\fB\-q \-q \-q\fR (or \fB\-qqq\fR): produce no output at all +.PP +\&\fB\-\-help\fR: prints the help +.PP +\&\fB\-\-version\fR: print the version of \fB\s-1UPX\s0\fR +.PP +\&\fB\-\-exact\fR: when compressing, require to be able to get a byte-identical file +after decompression with option \fB\-d\fR. [\s-1NOTE:\s0 this is work in progress and is +not supported for all formats yet. If you do care, as a workaround you can +compress and then decompress your program a first time \- any further +compress-decompress steps should then yield byte-identical results +as compared to the first decompressed version.] +.PP +[ ...to be written... \- type `\fBupx \-\-help\fR' for now ] +.SH "COMPRESSION LEVELS & TUNING" +.IX Header "COMPRESSION LEVELS & TUNING" +\&\fB\s-1UPX\s0\fR offers ten different compression levels from \fB\-1\fR to \fB\-9\fR, +and \fB\-\-best\fR. The default compression level is \fB\-8\fR for files +smaller than 512 KiB, and \fB\-7\fR otherwise. +.IP "\(bu" 4 +Compression levels 1, 2 and 3 are pretty fast. +.IP "\(bu" 4 +Compression levels 4, 5 and 6 achieve a good time/ratio performance. +.IP "\(bu" 4 +Compression levels 7, 8 and 9 favor compression ratio over speed. +.IP "\(bu" 4 +Compression level \fB\-\-best\fR may take a long time. +.PP +Note that compression level \fB\-\-best\fR can be somewhat slow for large +files, but you definitely should use it when releasing a final version +of your program. +.PP +Quick info for achieving the best compression ratio: +.IP "\(bu" 4 +Try \fBupx \-\-brute myfile.exe\fR or even \fBupx \-\-ultra\-brute myfile.exe\fR. +.IP "\(bu" 4 +Try if \fB\-\-overlay=strip\fR works. +.IP "\(bu" 4 +For win32/pe programs there's \fB\-\-strip\-relocs=0\fR. See notes below. +.SH "OVERLAY HANDLING OPTIONS" +.IX Header "OVERLAY HANDLING OPTIONS" +Info: An \*(L"overlay\*(R" means auxiliary data attached after the logical end of +an executable, and it often contains application specific data +(this is a common practice to avoid an extra data file, though +it would be better to use resource sections). +.PP +\&\fB\s-1UPX\s0\fR handles overlays like many other executable packers do: it simply +copies the overlay after the compressed image. This works with some +files, but doesn't work with others, depending on how an application +actually accesses this overlayed data. +.PP +.Vb 1 +\& \-\-overlay=copy Copy any extra data attached to the file. [DEFAULT] +\& +\& \-\-overlay=strip Strip any overlay from the program instead of +\& copying it. Be warned, this may make the compressed +\& program crash or otherwise unusable. +\& +\& \-\-overlay=skip Refuse to compress any program which has an overlay. +.Ve +.SH "ENVIRONMENT" +.IX Header "ENVIRONMENT" +The environment variable \fB\s-1UPX\s0\fR can hold a set of default +options for \fB\s-1UPX\s0\fR. These options are interpreted first and +can be overwritten by explicit command line parameters. +For example: +.PP +.Vb 3 +\& for DOS/Windows: set UPX=\-9 \-\-compress\-icons#0 +\& for sh/ksh/zsh: UPX="\-9 \-\-compress\-icons=0"; export UPX +\& for csh/tcsh: setenv UPX "\-9 \-\-compress\-icons=0" +.Ve +.PP +Under DOS/Windows you must use '#' instead of '=' when setting the +environment variable because of a \s-1COMMAND.COM\s0 limitation. +.PP +Not all of the options are valid in the environment variable \- +\&\fB\s-1UPX\s0\fR will tell you. +.PP +You can explicitly use the \fB\-\-no\-env\fR option to ignore the +environment variable. +.SH "NOTES FOR THE SUPPORTED EXECUTABLE FORMATS" +.IX Header "NOTES FOR THE SUPPORTED EXECUTABLE FORMATS" +.SS "\s-1NOTES FOR ATARI/TOS\s0" +.IX Subsection "NOTES FOR ATARI/TOS" +This is the executable format used by the Atari \s-1ST/TT,\s0 a Motorola 68000 +based personal computer which was popular in the late '80s. Support +of this format is only because of nostalgic feelings of one of +the authors and serves no practical purpose :\-). +See http://www.freemint.de for more info. +.PP +Packed programs will be byte-identical to the original after uncompression. +All debug information will be stripped, though. +.PP +Extra options available for this executable format: +.PP +.Vb 4 +\& \-\-all\-methods Compress the program several times, using all +\& available compression methods. This may improve +\& the compression ratio in some cases, but usually +\& the default method gives the best results anyway. +.Ve +.SS "\s-1NOTES FOR BVMLINUZ/I386\s0" +.IX Subsection "NOTES FOR BVMLINUZ/I386" +Same as vmlinuz/i386. +.SS "\s-1NOTES FOR DOS/COM\s0" +.IX Subsection "NOTES FOR DOS/COM" +Obviously \fB\s-1UPX\s0\fR won't work with executables that want to read data from +themselves (like some commandline utilities that ship with Win95/98/ME). +.PP +Compressed programs only work on a 286+. +.PP +Packed programs will be byte-identical to the original after uncompression. +.PP +Maximum uncompressed size: ~65100 bytes. +.PP +Extra options available for this executable format: +.PP +.Vb 1 +\& \-\-8086 Create an executable that works on any 8086 CPU. +\& +\& \-\-all\-methods Compress the program several times, using all +\& available compression methods. This may improve +\& the compression ratio in some cases, but usually +\& the default method gives the best results anyway. +\& +\& \-\-all\-filters Compress the program several times, using all +\& available preprocessing filters. This may improve +\& the compression ratio in some cases, but usually +\& the default filter gives the best results anyway. +.Ve +.SS "\s-1NOTES FOR DOS/EXE\s0" +.IX Subsection "NOTES FOR DOS/EXE" +dos/exe stands for all \*(L"normal\*(R" 16\-bit \s-1DOS\s0 executables. +.PP +Obviously \fB\s-1UPX\s0\fR won't work with executables that want to read data from +themselves (like some command line utilities that ship with Win95/98/ME). +.PP +Compressed programs only work on a 286+. +.PP +Extra options available for this executable format: +.PP +.Vb 1 +\& \-\-8086 Create an executable that works on any 8086 CPU. +\& +\& \-\-no\-reloc Use no relocation records in the exe header. +\& +\& \-\-all\-methods Compress the program several times, using all +\& available compression methods. This may improve +\& the compression ratio in some cases, but usually +\& the default method gives the best results anyway. +.Ve +.SS "\s-1NOTES FOR DOS/SYS\s0" +.IX Subsection "NOTES FOR DOS/SYS" +Compressed programs only work on a 286+. +.PP +Packed programs will be byte-identical to the original after uncompression. +.PP +Maximum uncompressed size: ~65350 bytes. +.PP +Extra options available for this executable format: +.PP +.Vb 1 +\& \-\-8086 Create an executable that works on any 8086 CPU. +\& +\& \-\-all\-methods Compress the program several times, using all +\& available compression methods. This may improve +\& the compression ratio in some cases, but usually +\& the default method gives the best results anyway. +\& +\& \-\-all\-filters Compress the program several times, using all +\& available preprocessing filters. This may improve +\& the compression ratio in some cases, but usually +\& the default filter gives the best results anyway. +.Ve +.SS "\s-1NOTES FOR DJGPP2/COFF\s0" +.IX Subsection "NOTES FOR DJGPP2/COFF" +First of all, it is recommended to use \fB\s-1UPX\s0\fR *instead* of \fBstrip\fR. strip has +the very bad habit of replacing your stub with its own (outdated) version. +Additionally \fB\s-1UPX\s0\fR corrects a bug/feature in strip v2.8.x: it +will fix the 4 KiB alignment of the stub. +.PP +\&\fB\s-1UPX\s0\fR includes the full functionality of stubify. This means it will +automatically stubify your \s-1COFF\s0 files. Use the option \fB\-\-coff\fR to +disable this functionality (see below). +.PP +\&\fB\s-1UPX\s0\fR automatically handles Allegro packfiles. +.PP +The \s-1DLM\s0 format (a rather exotic shared library extension) is not supported. +.PP +Packed programs will be byte-identical to the original after uncompression. +All debug information and trailing garbage will be stripped, though. +.PP +Extra options available for this executable format: +.PP +.Vb 2 +\& \-\-coff Produce COFF output instead of EXE. By default +\& UPX keeps your current stub. +\& +\& \-\-all\-methods Compress the program several times, using all +\& available compression methods. This may improve +\& the compression ratio in some cases, but usually +\& the default method gives the best results anyway. +\& +\& \-\-all\-filters Compress the program several times, using all +\& available preprocessing filters. This may improve +\& the compression ratio in some cases, but usually +\& the default filter gives the best results anyway. +.Ve +.SS "\s-1NOTES FOR LINUX\s0 [general]" +.IX Subsection "NOTES FOR LINUX [general]" +Introduction +.PP +.Vb 4 +\& Linux/386 support in UPX consists of 3 different executable formats, +\& one optimized for ELF executables ("linux/elf386"), one optimized +\& for shell scripts ("linux/sh386"), and one generic format +\& ("linux/386"). +\& +\& We will start with a general discussion first, but please +\& also read the relevant docs for each of the individual formats. +\& +\& Also, there is special support for bootable kernels \- see the +\& description of the vmlinuz/386 format. +.Ve +.PP +General user's overview +.PP +.Vb 7 +\& Running a compressed executable program trades less space on a +\& \`\`permanent\*(Aq\*(Aq storage medium (such as a hard disk, floppy disk, +\& CD\-ROM, flash memory, EPROM, etc.) for more space in one or more +\& \`\`temporary\*(Aq\*(Aq storage media (such as RAM, swap space, /tmp, etc.). +\& Running a compressed executable also requires some additional CPU +\& cycles to generate the compressed executable in the first place, +\& and to decompress it at each invocation. +\& +\& How much space is traded? It depends on the executable, but many +\& programs save 30% to 50% of permanent disk space. How much CPU +\& overhead is there? Again, it depends on the executable, but +\& decompression speed generally is at least many megabytes per second, +\& and frequently is limited by the speed of the underlying disk +\& or network I/O. +\& +\& Depending on the statistics of usage and access, and the relative +\& speeds of CPU, RAM, swap space, /tmp, and file system storage, then +\& invoking and running a compressed executable can be faster than +\& directly running the corresponding uncompressed program. +\& The operating system might perform fewer expensive I/O operations +\& to invoke the compressed program. Paging to or from swap space +\& or /tmp might be faster than paging from the general file system. +\& \`\`Medium\-sized\*(Aq\*(Aq programs which access about 1/3 to 1/2 of their +\& stored program bytes can do particularly well with compression. +\& Small programs tend not to benefit as much because the absolute +\& savings is less. Big programs tend not to benefit proportionally +\& because each invocation may use only a small fraction of the program, +\& yet UPX decompresses the entire program before invoking it. +\& But in environments where disk or flash memory storage is limited, +\& then compression may win anyway. +\& +\& Currently, executables compressed by UPX do not share RAM at runtime +\& in the way that executables mapped from a file system do. As a +\& result, if the same program is run simultaneously by more than one +\& process, then using the compressed version will require more RAM and/or +\& swap space. So, shell programs (bash, csh, etc.) and \`\`make\*(Aq\*(Aq +\& might not be good candidates for compression. +\& +\& UPX recognizes three executable formats for Linux: Linux/elf386, +\& Linux/sh386, and Linux/386. Linux/386 is the most generic format; +\& it accommodates any file that can be executed. At runtime, the UPX +\& decompression stub re\-creates in /tmp a copy of the original file, +\& and then the copy is (re\-)executed with the same arguments. +\& ELF binary executables prefer the Linux/elf386 format by default, +\& because UPX decompresses them directly into RAM, uses only one +\& exec, does not use space in /tmp, and does not use /proc. +\& Shell scripts where the underlying shell accepts a \`\`\-c\*(Aq\*(Aq argument +\& can use the Linux/sh386 format. UPX decompresses the shell script +\& into low memory, then maps the shell and passes the entire text of the +\& script as an argument with a leading \`\`\-c\*(Aq\*(Aq. +.Ve +.PP +General benefits: +.PP +.Vb 4 +\& \- UPX can compress all executables, be it AOUT, ELF, libc4, libc5, +\& libc6, Shell/Perl/Python/... scripts, standalone Java .class +\& binaries, or whatever... +\& All scripts and programs will work just as before. +\& +\& \- Compressed programs are completely self\-contained. No need for +\& any external program. +\& +\& \- UPX keeps your original program untouched. This means that +\& after decompression you will have a byte\-identical version, +\& and you can use UPX as a file compressor just like gzip. +\& [ Note that UPX maintains a checksum of the file internally, +\& so it is indeed a reliable alternative. ] +\& +\& \- As the stub only uses syscalls and isn\*(Aqt linked against libc it +\& should run under any Linux configuration that can run ELF +\& binaries. +\& +\& \- For the same reason compressed executables should run under +\& FreeBSD and other systems which can run Linux binaries. +\& [ Please send feedback on this topic ] +.Ve +.PP +General drawbacks: +.PP +.Vb 4 +\& \- It is not advisable to compress programs which usually have many +\& instances running (like \`sh\*(Aq or \`make\*(Aq) because the common segments of +\& compressed programs won\*(Aqt be shared any longer between different +\& processes. +\& +\& \- \`ldd\*(Aq and \`size\*(Aq won\*(Aqt show anything useful because all they +\& see is the statically linked stub. Since version 0.82 the section +\& headers are stripped from the UPX stub and \`size\*(Aq doesn\*(Aqt even +\& recognize the file format. The file patches/patch\-elfcode.h has a +\& patch to fix this bug in \`size\*(Aq and other programs which use GNU BFD. +.Ve +.PP +General notes: +.PP +.Vb 2 +\& \- As UPX leaves your original program untouched it is advantageous +\& to strip it before compression. +\& +\& \- If you compress a script you will lose platform independence \- +\& this could be a problem if you are using NFS mounted disks. +\& +\& \- Compression of suid, guid and sticky\-bit programs is rejected +\& because of possible security implications. +\& +\& \- For the same reason there is no sense in making any compressed +\& program suid. +\& +\& \- Obviously UPX won\*(Aqt work with executables that want to read data +\& from themselves. E.g., this might be a problem for Perl scripts +\& which access their _\|_DATA_\|_ lines. +\& +\& \- In case of internal errors the stub will abort with exitcode 127. +\& Typical reasons for this to happen are that the program has somehow +\& been modified after compression. +\& Running \`strace \-o strace.log compressed_file\*(Aq will tell you more. +.Ve +.SS "\s-1NOTES FOR LINUX/ELF386\s0" +.IX Subsection "NOTES FOR LINUX/ELF386" +Please read the general Linux description first. +.PP +The linux/elf386 format decompresses directly into \s-1RAM,\s0 +uses only one exec, does not use space in /tmp, +and does not use /proc. +.PP +Linux/elf386 is automatically selected for Linux \s-1ELF\s0 executables. +.PP +Packed programs will be byte-identical to the original after uncompression. +.PP +How it works: +.PP +.Vb 9 +\& For ELF executables, UPX decompresses directly to memory, simulating +\& the mapping that the operating system kernel uses during exec(), +\& including the PT_INTERP program interpreter (if any). +\& The brk() is set by a special PT_LOAD segment in the compressed +\& executable itself. UPX then wipes the stack clean except for +\& arguments, environment variables, and Elf_auxv entries (this is +\& required by bugs in the startup code of /lib/ld\-linux.so as of +\& May 2000), and transfers control to the program interpreter or +\& the e_entry address of the original executable. +\& +\& The UPX stub is about 1700 bytes long, partly written in assembler +\& and only uses kernel syscalls. It is not linked against any libc. +.Ve +.PP +Specific drawbacks: +.PP +.Vb 9 +\& \- For linux/elf386 and linux/sh386 formats, you will be relying on +\& RAM and swap space to hold all of the decompressed program during +\& the lifetime of the process. If you already use most of your swap +\& space, then you may run out. A system that is "out of memory" +\& can become fragile. Many programs do not react gracefully when +\& malloc() returns 0. With newer Linux kernels, the kernel +\& may decide to kill some processes to regain memory, and you +\& may not like the kernel\*(Aqs choice of which to kill. Running +\& /usr/bin/top is one way to check on the usage of swap space. +.Ve +.PP +Extra options available for this executable format: +.PP +.Vb 1 +\& (none) +.Ve +.SS "\s-1NOTES FOR LINUX/SH386\s0" +.IX Subsection "NOTES FOR LINUX/SH386" +Please read the general Linux description first. +.PP +Shell scripts where the underling shell accepts a ``\-c'' argument +can use the Linux/sh386 format. \fB\s-1UPX\s0\fR decompresses the shell script +into low memory, then maps the shell and passes the entire text of the +script as an argument with a leading ``\-c''. +It does not use space in /tmp, and does not use /proc. +.PP +Linux/sh386 is automatically selected for shell scripts that +use a known shell. +.PP +Packed programs will be byte-identical to the original after uncompression. +.PP +How it works: +.PP +.Vb 8 +\& For shell script executables (files beginning with "#!/" or "#! /") +\& where the shell is known to accept "\-c ", UPX decompresses +\& the file into low memory, then maps the shell (and its PT_INTERP), +\& and passes control to the shell with the entire decompressed file +\& as the argument after "\-c". Known shells are sh, ash, bash, bsh, csh, +\& ksh, tcsh, pdksh. Restriction: UPX cannot use this method +\& for shell scripts which use the one optional string argument after +\& the shell name in the script (example: "#! /bin/sh option3\en".) +\& +\& The UPX stub is about 1700 bytes long, partly written in assembler +\& and only uses kernel syscalls. It is not linked against any libc. +.Ve +.PP +Specific drawbacks: +.PP +.Vb 9 +\& \- For linux/elf386 and linux/sh386 formats, you will be relying on +\& RAM and swap space to hold all of the decompressed program during +\& the lifetime of the process. If you already use most of your swap +\& space, then you may run out. A system that is "out of memory" +\& can become fragile. Many programs do not react gracefully when +\& malloc() returns 0. With newer Linux kernels, the kernel +\& may decide to kill some processes to regain memory, and you +\& may not like the kernel\*(Aqs choice of which to kill. Running +\& /usr/bin/top is one way to check on the usage of swap space. +.Ve +.PP +Extra options available for this executable format: +.PP +.Vb 1 +\& (none) +.Ve +.SS "\s-1NOTES FOR LINUX/386\s0" +.IX Subsection "NOTES FOR LINUX/386" +Please read the general Linux description first. +.PP +The generic linux/386 format decompresses to /tmp and needs +/proc file system support. It starts the decompressed program +via the \fBexecve()\fR syscall. +.PP +Linux/386 is only selected if the specialized linux/elf386 +and linux/sh386 won't recognize a file. +.PP +Packed programs will be byte-identical to the original after uncompression. +.PP +How it works: +.PP +.Vb 7 +\& For files which are not ELF and not a script for a known "\-c" shell, +\& UPX uses kernel execve(), which first requires decompressing to a +\& temporary file in the file system. Interestingly \- +\& because of the good memory management of the Linux kernel \- this +\& often does not introduce a noticeable delay, and in fact there +\& will be no disk access at all if you have enough free memory as +\& the entire process takes places within the file system buffers. +\& +\& A compressed executable consists of the UPX stub and an overlay +\& which contains the original program in a compressed form. +\& +\& The UPX stub is a statically linked ELF executable and does +\& the following at program startup: +\& +\& 1) decompress the overlay to a temporary location in /tmp +\& 2) open the temporary file for reading +\& 3) try to delete the temporary file and start (execve) +\& the uncompressed program in /tmp using /proc//fd/X as +\& attained by step 2) +\& 4) if that fails, fork off a subprocess to clean up and +\& start the program in /tmp in the meantime +\& +\& The UPX stub is about 1700 bytes long, partly written in assembler +\& and only uses kernel syscalls. It is not linked against any libc. +.Ve +.PP +Specific drawbacks: +.PP +.Vb 4 +\& \- You need additional free disk space for the uncompressed program +\& in your /tmp directory. This program is deleted immediately after +\& decompression, but you still need it for the full execution time +\& of the program. +\& +\& \- You must have /proc file system support as the stub wants to open +\& /proc//exe and needs /proc//fd/X. This also means that you +\& cannot compress programs that are used during the boot sequence +\& before /proc is mounted. +\& +\& \- Utilities like \`top\*(Aq will display numerical values in the process +\& name field. This is because Linux computes the process name from +\& the first argument of the last execve syscall (which is typically +\& something like /proc//fd/3). +\& +\& \- Because of temporary decompression to disk the decompression speed +\& is not as fast as with the other executable formats. Still, I can see +\& no noticeable delay when starting programs like my ~3 MiB emacs (which +\& is less than 1 MiB when compressed :\-). +.Ve +.PP +Extra options available for this executable format: +.PP +.Vb 3 +\& \-\-force\-execve Force the use of the generic linux/386 "execve" +\& format, i.e. do not try the linux/elf386 and +\& linux/sh386 formats. +.Ve +.SS "\s-1NOTES FOR PS1/EXE\s0" +.IX Subsection "NOTES FOR PS1/EXE" +This is the executable format used by the Sony PlayStation (PSone), +a Mips R3000 based gaming console which is popular since the late '90s. +Support of this format is very similar to the Atari one, because of +nostalgic feelings of one of the authors. +.PP +Packed programs will be byte-identical to the original after uncompression, +until further notice. +.PP +Maximum uncompressed size: ~1.89 / ~7.60 MiB. +.PP +Notes: +.PP +.Vb 6 +\& \- UPX creates as default a suitable executable for CD\-Mastering +\& and console transfer. For a CD\-Master main executable you could also try +\& the special option "\-\-boot\-only" as described below. +\& It has been reported that upx packed executables are fully compatible with +\& the Sony PlayStation 2 (PS2, PStwo) and Sony PlayStation Portable (PSP) in +\& Sony PlayStation (PSone) emulation mode. +\& +\& \- Normally the packed files use the same memory areas like the uncompressed +\& versions, so they will not override other memory areas while unpacking. +\& If this isn\*(Aqt possible UPX will abort showing a \*(Aqpacked data overlap\*(Aq +\& error. With the "\-\-force" option UPX will relocate the loading address +\& for the packed file, but this isn\*(Aqt a real problem if it is a single or +\& the main executable. +.Ve +.PP +Extra options available for this executable format: +.PP +.Vb 4 +\& \-\-all\-methods Compress the program several times, using all +\& available compression methods. This may improve +\& the compression ratio in some cases, but usually +\& the default method gives the best results anyway. +\& +\& \-\-8\-bit Uses 8 bit size compression [default: 32 bit] +\& +\& \-\-8mib\-ram PSone has 8 MiB ram available [default: 2 MiB] +\& +\& \-\-boot\-only This format is for main exes and CD\-Mastering only ! +\& It may slightly improve the compression ratio, +\& decompression routines are faster than default ones. +\& But it cannot be used for console transfer ! +\& +\& \-\-no\-align This option disables CD mode 2 data sector format +\& alignment. May slightly improves the compression ratio, +\& but the compressed executable will not boot from a CD. +\& Use it for console transfer only ! +.Ve +.SS "\s-1NOTES FOR RTM32/PE\s0 and \s-1ARM/PE\s0" +.IX Subsection "NOTES FOR RTM32/PE and ARM/PE" +Same as win32/pe. +.SS "\s-1NOTES FOR TMT/ADAM\s0" +.IX Subsection "NOTES FOR TMT/ADAM" +This format is used by the \s-1TMT\s0 Pascal compiler \- see http://www.tmt.com/ . +.PP +Extra options available for this executable format: +.PP +.Vb 4 +\& \-\-all\-methods Compress the program several times, using all +\& available compression methods. This may improve +\& the compression ratio in some cases, but usually +\& the default method gives the best results anyway. +\& +\& \-\-all\-filters Compress the program several times, using all +\& available preprocessing filters. This may improve +\& the compression ratio in some cases, but usually +\& the default filter gives the best results anyway. +.Ve +.SS "\s-1NOTES FOR VMLINUZ/386\s0" +.IX Subsection "NOTES FOR VMLINUZ/386" +The vmlinuz/386 and bvmlinuz/386 formats take a gzip-compressed +bootable Linux kernel image (\*(L"vmlinuz\*(R", \*(L"zImage\*(R", \*(L"bzImage\*(R"), +gzip-decompress it and re-compress it with the \fB\s-1UPX\s0\fR compression method. +.PP +vmlinuz/386 is completely unrelated to the other Linux executable +formats, and it does not share any of their drawbacks. +.PP +Notes: +.PP +.Vb 3 +\& \- Be sure that "vmlinuz/386" or "bvmlinuz/386" is displayed +\& during compression \- otherwise a wrong executable format +\& may have been used, and the kernel won\*(Aqt boot. +.Ve +.PP +Benefits: +.PP +.Vb 4 +\& \- Better compression (but note that the kernel was already compressed, +\& so the improvement is not as large as with other formats). +\& Still, the bytes saved may be essential for special needs like +\& boot disks. +\& +\& For example, this is what I get for my 2.2.16 kernel: +\& 1589708 vmlinux +\& 641073 bzImage [original] +\& 560755 bzImage.upx [compressed by "upx \-9"] +\& +\& \- Much faster decompression at kernel boot time (but kernel +\& decompression speed is not really an issue these days). +.Ve +.PP +Drawbacks: +.PP +.Vb 1 +\& (none) +.Ve +.PP +Extra options available for this executable format: +.PP +.Vb 4 +\& \-\-all\-methods Compress the program several times, using all +\& available compression methods. This may improve +\& the compression ratio in some cases, but usually +\& the default method gives the best results anyway. +\& +\& \-\-all\-filters Compress the program several times, using all +\& available preprocessing filters. This may improve +\& the compression ratio in some cases, but usually +\& the default filter gives the best results anyway. +.Ve +.SS "\s-1NOTES FOR WATCOM/LE\s0" +.IX Subsection "NOTES FOR WATCOM/LE" +\&\fB\s-1UPX\s0\fR has been successfully tested with the following extenders: + \s-1DOS4G, DOS4GW, PMODE/W,\s0 DOS32a, CauseWay. + The \s-1WDOS/X\s0 extender is partly supported (for details + see the file bugs \s-1BUGS\s0). +.PP +DLLs and the \s-1LX\s0 format are not supported. +.PP +Extra options available for this executable format: +.PP +.Vb 2 +\& \-\-le Produce an unbound LE output instead of +\& keeping the current stub. +.Ve +.SS "\s-1NOTES FOR WIN32/PE\s0" +.IX Subsection "NOTES FOR WIN32/PE" +The \s-1PE\s0 support in \fB\s-1UPX\s0\fR is quite stable now, but probably there are +still some incompatibilities with some files. +.PP +Because of the way \fB\s-1UPX\s0\fR (and other packers for this format) works, you +can see increased memory usage of your compressed files because the whole +program is loaded into memory at startup. +If you start several instances of huge compressed programs you're +wasting memory because the common segments of the program won't +get shared across the instances. +On the other hand if you're compressing only smaller programs, or +running only one instance of larger programs, then this penalty is +smaller, but it's still there. +.PP +If you're running executables from network, then compressed programs +will load faster, and require less bandwidth during execution. +.PP +DLLs are supported. But \s-1UPX\s0 compressed DLLs can not share common data and +code when they got used by multiple applications. So compressing msvcrt.dll +is a waste of memory, but compressing the dll plugins of a particular +application may be a better idea. +.PP +Screensavers are supported, with the restriction that the filename +must end with \*(L".scr\*(R" (as screensavers are handled slightly different +than normal exe files). +.PP +\&\s-1UPX\s0 compressed \s-1PE\s0 files have some minor memory overhead (usually in the +10 \- 30 KiB range) which can be seen by specifying the \*(L"\-i\*(R" command +line switch during compression. +.PP +Extra options available for this executable format: +.PP +.Vb 9 +\& \-\-compress\-exports=0 Don\*(Aqt compress the export section. +\& Use this if you plan to run the compressed +\& program under Wine. +\& \-\-compress\-exports=1 Compress the export section. [DEFAULT] +\& Compression of the export section can improve the +\& compression ratio quite a bit but may not work +\& with all programs (like winword.exe). +\& UPX never compresses the export section of a DLL +\& regardless of this option. +\& +\& \-\-compress\-icons=0 Don\*(Aqt compress any icons. +\& \-\-compress\-icons=1 Compress all but the first icon. +\& \-\-compress\-icons=2 Compress all icons which are not in the +\& first icon directory. [DEFAULT] +\& \-\-compress\-icons=3 Compress all icons. +\& +\& \-\-compress\-resources=0 Don\*(Aqt compress any resources at all. +\& +\& \-\-keep\-resource=list Don\*(Aqt compress resources specified by the list. +\& The members of the list are separated by commas. +\& A list member has the following format: I. +\& I is the type of the resource. Standard types +\& must be specified as decimal numbers, user types can be +\& specified by decimal IDs or strings. I is the +\& identifier of the resource. It can be a decimal number +\& or a string. For example: +\& +\& \-\-keep\-resource=2/MYBITMAP,5,6/12345 +\& +\& UPX won\*(Aqt compress the named bitmap resource "MYBITMAP", +\& it leaves every dialog (5) resource uncompressed, and +\& it won\*(Aqt touch the string table resource with identifier +\& 12345. +\& +\& \-\-force Force compression even when there is an +\& unexpected value in a header field. +\& Use with care. +\& +\& \-\-strip\-relocs=0 Don\*(Aqt strip relocation records. +\& \-\-strip\-relocs=1 Strip relocation records. [DEFAULT] +\& This option only works on executables with base +\& address greater or equal to 0x400000. Usually the +\& compressed files becomes smaller, but some files +\& may become larger. Note that the resulting file will +\& not work under Windows 3.x (Win32s). +\& UPX never strips relocations from a DLL +\& regardless of this option. +\& +\& \-\-all\-methods Compress the program several times, using all +\& available compression methods. This may improve +\& the compression ratio in some cases, but usually +\& the default method gives the best results anyway. +\& +\& \-\-all\-filters Compress the program several times, using all +\& available preprocessing filters. This may improve +\& the compression ratio in some cases, but usually +\& the default filter gives the best results anyway. +.Ve +.SH "DIAGNOSTICS" +.IX Header "DIAGNOSTICS" +Exit status is normally 0; if an error occurs, exit status +is 1. If a warning occurs, exit status is 2. +.PP +\&\fB\s-1UPX\s0\fR's diagnostics are intended to be self-explanatory. +.SH "BUGS" +.IX Header "BUGS" +Please report all bugs immediately to the authors. +.SH "AUTHORS" +.IX Header "AUTHORS" +.Vb 2 +\& Markus F.X.J. Oberhumer +\& http://www.oberhumer.com +\& +\& Laszlo Molnar +\& +\& John F. Reiser +\& +\& Jens Medoch +.Ve +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (C) 1996\-2020 Markus Franz Xaver Johannes Oberhumer +.PP +Copyright (C) 1996\-2020 Laszlo Molnar +.PP +Copyright (C) 2000\-2020 John F. Reiser +.PP +Copyright (C) 2002\-2020 Jens Medoch +.PP +This program may be used freely, and you are welcome to +redistribute it under certain conditions. +.PP +This program is distributed in the hope that it will be useful, +but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of +\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0 See the +\&\fB\s-1UPX\s0 License Agreement\fR for more details. +.PP +You should have received a copy of the \s-1UPX\s0 License Agreement along +with this program; see the file \s-1LICENSE.\s0 If not, visit the \s-1UPX\s0 home page. diff --git a/tools/upx.doc b/tools/upx.doc new file mode 100644 index 0000000..175bd13 --- /dev/null +++ b/tools/upx.doc @@ -0,0 +1,844 @@ +NAME + upx - compress or expand executable files + +SYNOPSIS + upx [ *command* ] [ *options* ] *filename*... + +ABSTRACT + The Ultimate Packer for eXecutables + Copyright (c) 1996-2020 Markus Oberhumer, Laszlo Molnar & John Reiser + https://upx.github.io + + UPX is a portable, extendable, high-performance executable packer for + several different executable formats. It achieves an excellent + compression ratio and offers **very** fast decompression. Your + executables suffer no memory overhead or other drawbacks for most of the + formats supported, because of in-place decompression. + + While you may use UPX freely for both non-commercial and commercial + executables (for details see the file LICENSE), we would highly + appreciate if you credit UPX and ourselves in the documentation, + possibly including a reference to the UPX home page. Thanks. + + [ Using UPX in non-OpenSource applications without proper credits is + considered not politically correct ;-) ] + +DISCLAIMER + UPX comes with ABSOLUTELY NO WARRANTY; for details see the file LICENSE. + + This is the first production quality release, and we plan that future + 1.xx releases will be backward compatible with this version. + + Please report all problems or suggestions to the authors. Thanks. + +DESCRIPTION + UPX is a versatile executable packer with the following features: + + - excellent compression ratio: compresses better than zip/gzip, + use UPX to decrease the size of your distribution ! + + - very fast decompression: about 10 MiB/sec on an ancient Pentium 133, + about 200 MiB/sec on an Athlon XP 2000+. + + - no memory overhead for your compressed executables for most of the + supported formats + + - safe: you can list, test and unpack your executables + Also, a checksum of both the compressed and uncompressed file is + maintained internally. + + - universal: UPX can pack a number of executable formats: + * atari/tos + * bvmlinuz/386 [bootable Linux kernel] + * djgpp2/coff + * dos/com + * dos/exe + * dos/sys + * linux/386 + * linux/elf386 + * linux/sh386 + * ps1/exe + * rtm32/pe + * tmt/adam + * vmlinuz/386 [bootable Linux kernel] + * vmlinux/386 + * watcom/le (supporting DOS4G, PMODE/W, DOS32a and CauseWay) + * win32/pe (exe and dll) + * win64/pe (exe and dll) + * arm/pe (exe and dll) + * linux/elfamd64 + * linux/elfppc32 + * mach/elfppc32 + + - portable: UPX is written in portable endian-neutral C++ + + - extendable: because of the class layout it's very easy to support + new executable formats or add new compression algorithms + + - free: UPX can be distributed and used freely. And from version 0.99 + the full source code of UPX is released under the GNU General Public + License (GPL) ! + + You probably understand now why we call UPX the "*ultimate*" executable + packer. + +COMMANDS + Compress + This is the default operation, eg. upx yourfile.exe will compress the + file specified on the command line. + + Decompress + All UPX supported file formats can be unpacked using the -d switch, eg. + upx -d yourfile.exe will uncompress the file you've just compressed. + + Test + The -t command tests the integrity of the compressed and uncompressed + data, eg. upx -t yourfile.exe check whether your file can be safely + decompressed. Note, that this command doesn't check the whole file, only + the part that will be uncompressed during program execution. This means + that you should not use this command instead of a virus checker. + + List + The -l command prints out some information about the compressed files + specified on the command line as parameters, eg upx -l yourfile.exe + shows the compressed / uncompressed size and the compression ratio of + *yourfile.exe*. + +OPTIONS + -q: be quiet, suppress warnings + + -q -q (or -qq): be very quiet, suppress errors + + -q -q -q (or -qqq): produce no output at all + + --help: prints the help + + --version: print the version of UPX + + --exact: when compressing, require to be able to get a byte-identical + file after decompression with option -d. [NOTE: this is work in progress + and is not supported for all formats yet. If you do care, as a + workaround you can compress and then decompress your program a first + time - any further compress-decompress steps should then yield + byte-identical results as compared to the first decompressed version.] + + [ ...to be written... - type `upx --help' for now ] + +COMPRESSION LEVELS & TUNING + UPX offers ten different compression levels from -1 to -9, and --best. + The default compression level is -8 for files smaller than 512 KiB, and + -7 otherwise. + + * Compression levels 1, 2 and 3 are pretty fast. + + * Compression levels 4, 5 and 6 achieve a good time/ratio performance. + + * Compression levels 7, 8 and 9 favor compression ratio over speed. + + * Compression level --best may take a long time. + + Note that compression level --best can be somewhat slow for large files, + but you definitely should use it when releasing a final version of your + program. + + Quick info for achieving the best compression ratio: + + * Try upx --brute myfile.exe or even upx --ultra-brute myfile.exe. + + * Try if --overlay=strip works. + + * For win32/pe programs there's --strip-relocs=0. See notes below. + +OVERLAY HANDLING OPTIONS + Info: An "overlay" means auxiliary data attached after the logical end + of an executable, and it often contains application specific data (this + is a common practice to avoid an extra data file, though it would be + better to use resource sections). + + UPX handles overlays like many other executable packers do: it simply + copies the overlay after the compressed image. This works with some + files, but doesn't work with others, depending on how an application + actually accesses this overlayed data. + + --overlay=copy Copy any extra data attached to the file. [DEFAULT] + + --overlay=strip Strip any overlay from the program instead of + copying it. Be warned, this may make the compressed + program crash or otherwise unusable. + + --overlay=skip Refuse to compress any program which has an overlay. + +ENVIRONMENT + The environment variable UPX can hold a set of default options for UPX. + These options are interpreted first and can be overwritten by explicit + command line parameters. For example: + + for DOS/Windows: set UPX=-9 --compress-icons#0 + for sh/ksh/zsh: UPX="-9 --compress-icons=0"; export UPX + for csh/tcsh: setenv UPX "-9 --compress-icons=0" + + Under DOS/Windows you must use '#' instead of '=' when setting the + environment variable because of a COMMAND.COM limitation. + + Not all of the options are valid in the environment variable - UPX will + tell you. + + You can explicitly use the --no-env option to ignore the environment + variable. + +NOTES FOR THE SUPPORTED EXECUTABLE FORMATS + NOTES FOR ATARI/TOS + This is the executable format used by the Atari ST/TT, a Motorola 68000 + based personal computer which was popular in the late '80s. Support of + this format is only because of nostalgic feelings of one of the authors + and serves no practical purpose :-). See http://www.freemint.de for more + info. + + Packed programs will be byte-identical to the original after + uncompression. All debug information will be stripped, though. + + Extra options available for this executable format: + + --all-methods Compress the program several times, using all + available compression methods. This may improve + the compression ratio in some cases, but usually + the default method gives the best results anyway. + + NOTES FOR BVMLINUZ/I386 + Same as vmlinuz/i386. + + NOTES FOR DOS/COM + Obviously UPX won't work with executables that want to read data from + themselves (like some commandline utilities that ship with Win95/98/ME). + + Compressed programs only work on a 286+. + + Packed programs will be byte-identical to the original after + uncompression. + + Maximum uncompressed size: ~65100 bytes. + + Extra options available for this executable format: + + --8086 Create an executable that works on any 8086 CPU. + + --all-methods Compress the program several times, using all + available compression methods. This may improve + the compression ratio in some cases, but usually + the default method gives the best results anyway. + + --all-filters Compress the program several times, using all + available preprocessing filters. This may improve + the compression ratio in some cases, but usually + the default filter gives the best results anyway. + + NOTES FOR DOS/EXE + dos/exe stands for all "normal" 16-bit DOS executables. + + Obviously UPX won't work with executables that want to read data from + themselves (like some command line utilities that ship with + Win95/98/ME). + + Compressed programs only work on a 286+. + + Extra options available for this executable format: + + --8086 Create an executable that works on any 8086 CPU. + + --no-reloc Use no relocation records in the exe header. + + --all-methods Compress the program several times, using all + available compression methods. This may improve + the compression ratio in some cases, but usually + the default method gives the best results anyway. + + NOTES FOR DOS/SYS + Compressed programs only work on a 286+. + + Packed programs will be byte-identical to the original after + uncompression. + + Maximum uncompressed size: ~65350 bytes. + + Extra options available for this executable format: + + --8086 Create an executable that works on any 8086 CPU. + + --all-methods Compress the program several times, using all + available compression methods. This may improve + the compression ratio in some cases, but usually + the default method gives the best results anyway. + + --all-filters Compress the program several times, using all + available preprocessing filters. This may improve + the compression ratio in some cases, but usually + the default filter gives the best results anyway. + + NOTES FOR DJGPP2/COFF + First of all, it is recommended to use UPX *instead* of strip. strip has + the very bad habit of replacing your stub with its own (outdated) + version. Additionally UPX corrects a bug/feature in strip v2.8.x: it + will fix the 4 KiB alignment of the stub. + + UPX includes the full functionality of stubify. This means it will + automatically stubify your COFF files. Use the option --coff to disable + this functionality (see below). + + UPX automatically handles Allegro packfiles. + + The DLM format (a rather exotic shared library extension) is not + supported. + + Packed programs will be byte-identical to the original after + uncompression. All debug information and trailing garbage will be + stripped, though. + + Extra options available for this executable format: + + --coff Produce COFF output instead of EXE. By default + UPX keeps your current stub. + + --all-methods Compress the program several times, using all + available compression methods. This may improve + the compression ratio in some cases, but usually + the default method gives the best results anyway. + + --all-filters Compress the program several times, using all + available preprocessing filters. This may improve + the compression ratio in some cases, but usually + the default filter gives the best results anyway. + + NOTES FOR LINUX [general] + Introduction + + Linux/386 support in UPX consists of 3 different executable formats, + one optimized for ELF executables ("linux/elf386"), one optimized + for shell scripts ("linux/sh386"), and one generic format + ("linux/386"). + + We will start with a general discussion first, but please + also read the relevant docs for each of the individual formats. + + Also, there is special support for bootable kernels - see the + description of the vmlinuz/386 format. + + General user's overview + + Running a compressed executable program trades less space on a + ``permanent'' storage medium (such as a hard disk, floppy disk, + CD-ROM, flash memory, EPROM, etc.) for more space in one or more + ``temporary'' storage media (such as RAM, swap space, /tmp, etc.). + Running a compressed executable also requires some additional CPU + cycles to generate the compressed executable in the first place, + and to decompress it at each invocation. + + How much space is traded? It depends on the executable, but many + programs save 30% to 50% of permanent disk space. How much CPU + overhead is there? Again, it depends on the executable, but + decompression speed generally is at least many megabytes per second, + and frequently is limited by the speed of the underlying disk + or network I/O. + + Depending on the statistics of usage and access, and the relative + speeds of CPU, RAM, swap space, /tmp, and file system storage, then + invoking and running a compressed executable can be faster than + directly running the corresponding uncompressed program. + The operating system might perform fewer expensive I/O operations + to invoke the compressed program. Paging to or from swap space + or /tmp might be faster than paging from the general file system. + ``Medium-sized'' programs which access about 1/3 to 1/2 of their + stored program bytes can do particularly well with compression. + Small programs tend not to benefit as much because the absolute + savings is less. Big programs tend not to benefit proportionally + because each invocation may use only a small fraction of the program, + yet UPX decompresses the entire program before invoking it. + But in environments where disk or flash memory storage is limited, + then compression may win anyway. + + Currently, executables compressed by UPX do not share RAM at runtime + in the way that executables mapped from a file system do. As a + result, if the same program is run simultaneously by more than one + process, then using the compressed version will require more RAM and/or + swap space. So, shell programs (bash, csh, etc.) and ``make'' + might not be good candidates for compression. + + UPX recognizes three executable formats for Linux: Linux/elf386, + Linux/sh386, and Linux/386. Linux/386 is the most generic format; + it accommodates any file that can be executed. At runtime, the UPX + decompression stub re-creates in /tmp a copy of the original file, + and then the copy is (re-)executed with the same arguments. + ELF binary executables prefer the Linux/elf386 format by default, + because UPX decompresses them directly into RAM, uses only one + exec, does not use space in /tmp, and does not use /proc. + Shell scripts where the underlying shell accepts a ``-c'' argument + can use the Linux/sh386 format. UPX decompresses the shell script + into low memory, then maps the shell and passes the entire text of the + script as an argument with a leading ``-c''. + + General benefits: + + - UPX can compress all executables, be it AOUT, ELF, libc4, libc5, + libc6, Shell/Perl/Python/... scripts, standalone Java .class + binaries, or whatever... + All scripts and programs will work just as before. + + - Compressed programs are completely self-contained. No need for + any external program. + + - UPX keeps your original program untouched. This means that + after decompression you will have a byte-identical version, + and you can use UPX as a file compressor just like gzip. + [ Note that UPX maintains a checksum of the file internally, + so it is indeed a reliable alternative. ] + + - As the stub only uses syscalls and isn't linked against libc it + should run under any Linux configuration that can run ELF + binaries. + + - For the same reason compressed executables should run under + FreeBSD and other systems which can run Linux binaries. + [ Please send feedback on this topic ] + + General drawbacks: + + - It is not advisable to compress programs which usually have many + instances running (like `sh' or `make') because the common segments of + compressed programs won't be shared any longer between different + processes. + + - `ldd' and `size' won't show anything useful because all they + see is the statically linked stub. Since version 0.82 the section + headers are stripped from the UPX stub and `size' doesn't even + recognize the file format. The file patches/patch-elfcode.h has a + patch to fix this bug in `size' and other programs which use GNU BFD. + + General notes: + + - As UPX leaves your original program untouched it is advantageous + to strip it before compression. + + - If you compress a script you will lose platform independence - + this could be a problem if you are using NFS mounted disks. + + - Compression of suid, guid and sticky-bit programs is rejected + because of possible security implications. + + - For the same reason there is no sense in making any compressed + program suid. + + - Obviously UPX won't work with executables that want to read data + from themselves. E.g., this might be a problem for Perl scripts + which access their __DATA__ lines. + + - In case of internal errors the stub will abort with exitcode 127. + Typical reasons for this to happen are that the program has somehow + been modified after compression. + Running `strace -o strace.log compressed_file' will tell you more. + + NOTES FOR LINUX/ELF386 + Please read the general Linux description first. + + The linux/elf386 format decompresses directly into RAM, uses only one + exec, does not use space in /tmp, and does not use /proc. + + Linux/elf386 is automatically selected for Linux ELF executables. + + Packed programs will be byte-identical to the original after + uncompression. + + How it works: + + For ELF executables, UPX decompresses directly to memory, simulating + the mapping that the operating system kernel uses during exec(), + including the PT_INTERP program interpreter (if any). + The brk() is set by a special PT_LOAD segment in the compressed + executable itself. UPX then wipes the stack clean except for + arguments, environment variables, and Elf_auxv entries (this is + required by bugs in the startup code of /lib/ld-linux.so as of + May 2000), and transfers control to the program interpreter or + the e_entry address of the original executable. + + The UPX stub is about 1700 bytes long, partly written in assembler + and only uses kernel syscalls. It is not linked against any libc. + + Specific drawbacks: + + - For linux/elf386 and linux/sh386 formats, you will be relying on + RAM and swap space to hold all of the decompressed program during + the lifetime of the process. If you already use most of your swap + space, then you may run out. A system that is "out of memory" + can become fragile. Many programs do not react gracefully when + malloc() returns 0. With newer Linux kernels, the kernel + may decide to kill some processes to regain memory, and you + may not like the kernel's choice of which to kill. Running + /usr/bin/top is one way to check on the usage of swap space. + + Extra options available for this executable format: + + (none) + + NOTES FOR LINUX/SH386 + Please read the general Linux description first. + + Shell scripts where the underling shell accepts a ``-c'' argument can + use the Linux/sh386 format. UPX decompresses the shell script into low + memory, then maps the shell and passes the entire text of the script as + an argument with a leading ``-c''. It does not use space in /tmp, and + does not use /proc. + + Linux/sh386 is automatically selected for shell scripts that use a known + shell. + + Packed programs will be byte-identical to the original after + uncompression. + + How it works: + + For shell script executables (files beginning with "#!/" or "#! /") + where the shell is known to accept "-c ", UPX decompresses + the file into low memory, then maps the shell (and its PT_INTERP), + and passes control to the shell with the entire decompressed file + as the argument after "-c". Known shells are sh, ash, bash, bsh, csh, + ksh, tcsh, pdksh. Restriction: UPX cannot use this method + for shell scripts which use the one optional string argument after + the shell name in the script (example: "#! /bin/sh option3\n".) + + The UPX stub is about 1700 bytes long, partly written in assembler + and only uses kernel syscalls. It is not linked against any libc. + + Specific drawbacks: + + - For linux/elf386 and linux/sh386 formats, you will be relying on + RAM and swap space to hold all of the decompressed program during + the lifetime of the process. If you already use most of your swap + space, then you may run out. A system that is "out of memory" + can become fragile. Many programs do not react gracefully when + malloc() returns 0. With newer Linux kernels, the kernel + may decide to kill some processes to regain memory, and you + may not like the kernel's choice of which to kill. Running + /usr/bin/top is one way to check on the usage of swap space. + + Extra options available for this executable format: + + (none) + + NOTES FOR LINUX/386 + Please read the general Linux description first. + + The generic linux/386 format decompresses to /tmp and needs /proc file + system support. It starts the decompressed program via the execve() + syscall. + + Linux/386 is only selected if the specialized linux/elf386 and + linux/sh386 won't recognize a file. + + Packed programs will be byte-identical to the original after + uncompression. + + How it works: + + For files which are not ELF and not a script for a known "-c" shell, + UPX uses kernel execve(), which first requires decompressing to a + temporary file in the file system. Interestingly - + because of the good memory management of the Linux kernel - this + often does not introduce a noticeable delay, and in fact there + will be no disk access at all if you have enough free memory as + the entire process takes places within the file system buffers. + + A compressed executable consists of the UPX stub and an overlay + which contains the original program in a compressed form. + + The UPX stub is a statically linked ELF executable and does + the following at program startup: + + 1) decompress the overlay to a temporary location in /tmp + 2) open the temporary file for reading + 3) try to delete the temporary file and start (execve) + the uncompressed program in /tmp using /proc//fd/X as + attained by step 2) + 4) if that fails, fork off a subprocess to clean up and + start the program in /tmp in the meantime + + The UPX stub is about 1700 bytes long, partly written in assembler + and only uses kernel syscalls. It is not linked against any libc. + + Specific drawbacks: + + - You need additional free disk space for the uncompressed program + in your /tmp directory. This program is deleted immediately after + decompression, but you still need it for the full execution time + of the program. + + - You must have /proc file system support as the stub wants to open + /proc//exe and needs /proc//fd/X. This also means that you + cannot compress programs that are used during the boot sequence + before /proc is mounted. + + - Utilities like `top' will display numerical values in the process + name field. This is because Linux computes the process name from + the first argument of the last execve syscall (which is typically + something like /proc//fd/3). + + - Because of temporary decompression to disk the decompression speed + is not as fast as with the other executable formats. Still, I can see + no noticeable delay when starting programs like my ~3 MiB emacs (which + is less than 1 MiB when compressed :-). + + Extra options available for this executable format: + + --force-execve Force the use of the generic linux/386 "execve" + format, i.e. do not try the linux/elf386 and + linux/sh386 formats. + + NOTES FOR PS1/EXE + This is the executable format used by the Sony PlayStation (PSone), a + Mips R3000 based gaming console which is popular since the late '90s. + Support of this format is very similar to the Atari one, because of + nostalgic feelings of one of the authors. + + Packed programs will be byte-identical to the original after + uncompression, until further notice. + + Maximum uncompressed size: ~1.89 / ~7.60 MiB. + + Notes: + + - UPX creates as default a suitable executable for CD-Mastering + and console transfer. For a CD-Master main executable you could also try + the special option "--boot-only" as described below. + It has been reported that upx packed executables are fully compatible with + the Sony PlayStation 2 (PS2, PStwo) and Sony PlayStation Portable (PSP) in + Sony PlayStation (PSone) emulation mode. + + - Normally the packed files use the same memory areas like the uncompressed + versions, so they will not override other memory areas while unpacking. + If this isn't possible UPX will abort showing a 'packed data overlap' + error. With the "--force" option UPX will relocate the loading address + for the packed file, but this isn't a real problem if it is a single or + the main executable. + + Extra options available for this executable format: + + --all-methods Compress the program several times, using all + available compression methods. This may improve + the compression ratio in some cases, but usually + the default method gives the best results anyway. + + --8-bit Uses 8 bit size compression [default: 32 bit] + + --8mib-ram PSone has 8 MiB ram available [default: 2 MiB] + + --boot-only This format is for main exes and CD-Mastering only ! + It may slightly improve the compression ratio, + decompression routines are faster than default ones. + But it cannot be used for console transfer ! + + --no-align This option disables CD mode 2 data sector format + alignment. May slightly improves the compression ratio, + but the compressed executable will not boot from a CD. + Use it for console transfer only ! + + NOTES FOR RTM32/PE and ARM/PE + Same as win32/pe. + + NOTES FOR TMT/ADAM + This format is used by the TMT Pascal compiler - see http://www.tmt.com/ + . + + Extra options available for this executable format: + + --all-methods Compress the program several times, using all + available compression methods. This may improve + the compression ratio in some cases, but usually + the default method gives the best results anyway. + + --all-filters Compress the program several times, using all + available preprocessing filters. This may improve + the compression ratio in some cases, but usually + the default filter gives the best results anyway. + + NOTES FOR VMLINUZ/386 + The vmlinuz/386 and bvmlinuz/386 formats take a gzip-compressed bootable + Linux kernel image ("vmlinuz", "zImage", "bzImage"), gzip-decompress it + and re-compress it with the UPX compression method. + + vmlinuz/386 is completely unrelated to the other Linux executable + formats, and it does not share any of their drawbacks. + + Notes: + + - Be sure that "vmlinuz/386" or "bvmlinuz/386" is displayed + during compression - otherwise a wrong executable format + may have been used, and the kernel won't boot. + + Benefits: + + - Better compression (but note that the kernel was already compressed, + so the improvement is not as large as with other formats). + Still, the bytes saved may be essential for special needs like + boot disks. + + For example, this is what I get for my 2.2.16 kernel: + 1589708 vmlinux + 641073 bzImage [original] + 560755 bzImage.upx [compressed by "upx -9"] + + - Much faster decompression at kernel boot time (but kernel + decompression speed is not really an issue these days). + + Drawbacks: + + (none) + + Extra options available for this executable format: + + --all-methods Compress the program several times, using all + available compression methods. This may improve + the compression ratio in some cases, but usually + the default method gives the best results anyway. + + --all-filters Compress the program several times, using all + available preprocessing filters. This may improve + the compression ratio in some cases, but usually + the default filter gives the best results anyway. + + NOTES FOR WATCOM/LE + UPX has been successfully tested with the following extenders: DOS4G, + DOS4GW, PMODE/W, DOS32a, CauseWay. The WDOS/X extender is partly + supported (for details see the file bugs BUGS). + + DLLs and the LX format are not supported. + + Extra options available for this executable format: + + --le Produce an unbound LE output instead of + keeping the current stub. + + NOTES FOR WIN32/PE + The PE support in UPX is quite stable now, but probably there are still + some incompatibilities with some files. + + Because of the way UPX (and other packers for this format) works, you + can see increased memory usage of your compressed files because the + whole program is loaded into memory at startup. If you start several + instances of huge compressed programs you're wasting memory because the + common segments of the program won't get shared across the instances. On + the other hand if you're compressing only smaller programs, or running + only one instance of larger programs, then this penalty is smaller, but + it's still there. + + If you're running executables from network, then compressed programs + will load faster, and require less bandwidth during execution. + + DLLs are supported. But UPX compressed DLLs can not share common data + and code when they got used by multiple applications. So compressing + msvcrt.dll is a waste of memory, but compressing the dll plugins of a + particular application may be a better idea. + + Screensavers are supported, with the restriction that the filename must + end with ".scr" (as screensavers are handled slightly different than + normal exe files). + + UPX compressed PE files have some minor memory overhead (usually in the + 10 - 30 KiB range) which can be seen by specifying the "-i" command line + switch during compression. + + Extra options available for this executable format: + + --compress-exports=0 Don't compress the export section. + Use this if you plan to run the compressed + program under Wine. + --compress-exports=1 Compress the export section. [DEFAULT] + Compression of the export section can improve the + compression ratio quite a bit but may not work + with all programs (like winword.exe). + UPX never compresses the export section of a DLL + regardless of this option. + + --compress-icons=0 Don't compress any icons. + --compress-icons=1 Compress all but the first icon. + --compress-icons=2 Compress all icons which are not in the + first icon directory. [DEFAULT] + --compress-icons=3 Compress all icons. + + --compress-resources=0 Don't compress any resources at all. + + --keep-resource=list Don't compress resources specified by the list. + The members of the list are separated by commas. + A list member has the following format: I. + I is the type of the resource. Standard types + must be specified as decimal numbers, user types can be + specified by decimal IDs or strings. I is the + identifier of the resource. It can be a decimal number + or a string. For example: + + --keep-resource=2/MYBITMAP,5,6/12345 + + UPX won't compress the named bitmap resource "MYBITMAP", + it leaves every dialog (5) resource uncompressed, and + it won't touch the string table resource with identifier + 12345. + + --force Force compression even when there is an + unexpected value in a header field. + Use with care. + + --strip-relocs=0 Don't strip relocation records. + --strip-relocs=1 Strip relocation records. [DEFAULT] + This option only works on executables with base + address greater or equal to 0x400000. Usually the + compressed files becomes smaller, but some files + may become larger. Note that the resulting file will + not work under Windows 3.x (Win32s). + UPX never strips relocations from a DLL + regardless of this option. + + --all-methods Compress the program several times, using all + available compression methods. This may improve + the compression ratio in some cases, but usually + the default method gives the best results anyway. + + --all-filters Compress the program several times, using all + available preprocessing filters. This may improve + the compression ratio in some cases, but usually + the default filter gives the best results anyway. + +DIAGNOSTICS + Exit status is normally 0; if an error occurs, exit status is 1. If a + warning occurs, exit status is 2. + + UPX's diagnostics are intended to be self-explanatory. + +BUGS + Please report all bugs immediately to the authors. + +AUTHORS + Markus F.X.J. Oberhumer + http://www.oberhumer.com + + Laszlo Molnar + + John F. Reiser + + Jens Medoch + +COPYRIGHT + Copyright (C) 1996-2020 Markus Franz Xaver Johannes Oberhumer + + Copyright (C) 1996-2020 Laszlo Molnar + + Copyright (C) 2000-2020 John F. Reiser + + Copyright (C) 2002-2020 Jens Medoch + + This program may be used freely, and you are welcome to redistribute it + under certain conditions. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the UPX License + Agreement for more details. + + You should have received a copy of the UPX License Agreement along with + this program; see the file LICENSE. If not, visit the UPX home page. + diff --git a/tools/upx.exe b/tools/upx.exe new file mode 100644 index 0000000..436082b Binary files /dev/null and b/tools/upx.exe differ