@database MakeSFX.guide @author Kyzer/CSG @$VER: MakeSFX.guide 1.3 (27.12.98) @remark you can read this in a text viewer, if you need to. @node main "MakeSFX v1.3 documentation" @{u}MakeSFX v1.3@{uu} @{" " link intro} Introduction @{" " link install} Installing MakeSFX @{" " link usage} Using MakeSFX @{" " link options} MakeSFX options @{" " link history} MakeSFX history @{" " link credits} Credits MakeSFX is a program to create self-extracting archives. Copyright (C) 1997-1999 Kyzer/CSG 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., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. @{"Contacting the author" link credits} @endnode @node intro "Introduction" MakeSFX is a very simple creator for SelF eXtracting files - executable programs which extract a set of files inside them when run. They can also run AmigaDOS commands after extracting the files. The intended use is not for archiving or distribution - for that purpose, I recommend using Stefan Boberg's excellent LhASFX. Instead, MakeSFX is designed to create 'boot-up' installation files, for example copying environment files to ENV: on a network machine. @{"Installing MakeSFX" link install} @{"Using MakeSFX." link usage} @endnode @node install "Installing MakeSFX" @{b}Requirements@{ub} MakeSFX requires the PhxAss assembler by Frank Wille (available on Aminet: dev/asm/PhxAss*.lha). If you want to crunch your output files, then you also require StoneCracker by Jouni Kohornen (util/pack/stc*.lha). @{b}Installation@{ub} To install MakeSFX, simply copy MakeSFX to your C: directory and ensure the script bit (S) is set, like so: Copy MakeSFX to C: Protect C:MakeSFX SRWED Of course you should copy the 'PhxAss' and 'stc' executables to C: as well. @endnode @node usage "Using MakeSFX" The method of operation is as follows: - You run MakeSFX with appropriate arguments in the shell - name of output executable - directory and filepattern to select files - (optional) commands to execute after extraction - MakeSFX will list all the files you selected, with the exact filenames it will store in the executable. - MakeSFX will generate an assembly language file, containing entries for all the listed files. - MakeSFX will run an assembler (PhxAss) on the file, which will create an executable file containing all the selected files, and code to extract them. You now have an executable self-extracting archive program. - When run, this executable will recreate the files stored within it, with the same filenames as listed by MakeSFX originally. See the @{"note about files" link filenote} - This executable can then, after file extraction, execute a series of stored AmigaDOS commands. @{"Limitations of MakeSFX" link limitations} @{"MakeSFX options" link options} @endnode @node filenote "NOTE ABOUT FILES" If the filenames are absolute, that is they contain a device name followed by a ':', like 'ENV:' or 'RAM:', then the file in the executable will always be extracted to that absolute path. If the filenames are relative, then where the archive extracts to will be relative to the current directory, which may be different from the current directory where MakeSFX was run. Example: cd RAM: MakeSFX TMP:file1 RAM:blah/ MakeSFX TMP:file2 blah/ cd TMP: file1.exe unpacks to RAM:blah/ file2.exe unpacks to TMP:blah/ @endnode @node limitations "Limitations of MakeSFX" - The created executables need to load totally into memory, and if crunched require even more memory, so bear this in mind for how large you make your executables, and if you are extracting to the RAM: disk. - LhASFX is far better when people other than yourself will be running the the output executable. - Only the file data and its name are stored in the executable, not the file comment or file attributes. - You cannot use quote or doublequote symbols with the EXECUTE option, even if they are preceded with a '*'. @endnode @node options "MakeSFX options" You may set how MakeSFX operates using the following options. MakeSFX OUTPUTFILE, DIRECTORY, PATTERN, EXECUTE, ALL/S, CRUNCH/S, QUIET/S, NOEXT/S for example: MakeSFX S:env_setup ENV: ALL CRUNCH @{" " link OUTPUTFILE} OUTPUTFILE @{" " link DIRECTORY} DIRECTORY @{" " link PATTERN} PATTERN @{" " link EXECUTE} EXECUTE @{" " link ALL} ALL @{" " link CRUNCH} CRUNCH @{" " link QUIET} QUIET @{" " link NOEXT} NOEXT @endnode @node OUTPUTFILE "OUTPUTFILE option" OUTPUTFILE This is the name of the executable self extracting archive that will be created. The default name, if you do not specify one, is 'make.exe' @endnode @node DIRECTORY "DIRECTORY option" DIRECTORY This is the directory where filenames will be taken from to be built into a self extracting archive. You can specify an absolute directory (like RAM:blah/) or a relative directory, relative to the current directory. See the @{"note about filenames" link filenote}. If you do not specify a directory, the default is the current directory. @endnode @node PATTERN "PATTERN option" PATTERN As well as selecting the directory where to take files from, you can further restrict the choice by using a standard AmigaDOS pattern to select which files will be included. The default is '#?' (all files). @endnode @node EXECUTE "EXECUTE option" EXECUTE Executables created with MakeSFX can not only extract files to disk, they can also execute your choice of AmigaDOS commands after extracting. You specify commands in the same way you would type them at a prompt. To specify more than one command, you must seperate each command with a single "\\n", (you cannot use the usual AmigaDOS standard "*n"). Note that although you can create 'scripts' in this way, you can not perform scripting commands such as 'If' and 'Quit', for that you should put the commands in a file, and then use the 'Execute' command to run the script. Also note that the created executables will not quit (and thus free the memory used by all the files they are holding) until the executed commands have finished. It is more economical with memory to execute the desired commands AFTER running the executables. Examples: EXECUTE "start_magic" Runs the command 'start_magic' in the path or current directory after extracting files. EXECUTE="list\\nparp" Runs the command 'list', then the command 'parp', after extracting files. @endnode @node ALL "ALL option" ALL/S With the ALL switch, not only the files in your chosen directory will be added, also any files in subdirectories in your chosen directory, provided they match the file pattern. @endnode @node CRUNCH "CRUNCH option" CRUNCH/S If you select this option, the output executable will be compressed with StoneCracker. (If you prefer using another compressor, you can change the script to what you like). @endnode @node QUIET "QUIET option" QUIET/S If you select this option, MakeSFX will not print any information to the screen, it will simply do the work specified. @endnode @node NOEXT "NOEXT option" NOEXT/S MakeSFX normally adds the extension '.exe' to what you specify as the output file's name. You can specify this option to remove that feature. @endnode @node history "MakeSFX history" 1.0: Ancient history. 1.1: Second release (10.08.98) Can now expand multi-level directories. Now executables return an error code on failure. @{"ALL" link ALL} keyword. Included documented & readable @{"source code" link source}. 1.2: Third release (16.08.98) Added @{"EXECUTE" link EXECUTE} option. Fixed "Making self-extracting archive of ..." info 1.3: Fourth release (09.01.99) Added @{"QUIET" link QUIET} and @{"NOEXT" link NOEXT} options. Improved documentation. @{" Future development " link future} @endnode @node future "Future prospects for MakeSFX" - conversion to asm or E and build raw output - store file attributes and file comment Any further suggestions from you are very welcome. @{"Contact me." link credits} @endnode @node credits "Credits" MakeSFX is an AmigaDOS script created by Kyzer/CSG. It uses PhxAss by Frank Wille and StoneCracker by Jouni 'Mr.Spiv' Korhonen. The very excellent LhASFX was written by Stefan Boberg. Contact: Kyzer/CSG, 49 Fairview Road, AB22 8ZG, Scotland. or email: kyzer@4u.net @endnode @node source "The assembler source" ; this is the code generated by MakeSFX, in a readable form include lvo/exec_lib.i include lvo/dos_lib.i include dos/dos.i include exec/types.i MakeSFX move.l 4.w,a6 lea dosname(pc),a1 moveq #LIBRARY_MINIMUM,d0 jsr _LVOOpenLibrary(a6) tst.l d0 bne.s .ok moveq #RETURN_FAIL,d0 rts .ok move.l d0,a6 ; a6 = dosbase move.l sp,a5 ; a5 = original lea extract(pc),a4 ; a4 = extract() moveq #RETURN_OK,d7 ; d7 = returncode bsr start ; perform extractions ;---THIS PART INSERTED IF 'EXECUTECMD' OPTION USED lea execcmd(pc),a0 move.l a0,d1 moveq #0,d2 moveq #0,d3 jsr _LVOExecute(a6) ;------------------------------- bra end extract move.l (a3),a2 ; get pathname/filename .again tst.b (a2) ; loop through all characters beq.s .done cmp.b #"/",(a2) ; found a directory component? bne.s .notdir clr.b (a2) move.l (a3),d1 move.l #EXCLUSIVE_LOCK,d2 jsr _LVOLock(a6) move.l d0,d1 bne.s .lockok move.l (a3),d1 jsr _LVOCreateDir(a6) ; either lock it or create it .lockok move.b #"/",(a2) move.l d0,d1 beq.s fail ; fail if still doesn't exist jsr _LVOUnLock(a6) .notdir add #1,a2 bra.s .again .done move.l (a3)+,d1 ; get filename move.l #MODE_NEWFILE,d2 jsr _LVOOpen(a6) move.l d0,d5 beq.s fail move.l d5,d1 move.l (a3)+,d2 ; get filedata move.l (a3)+,d3 ; get filename jsr _LVOWrite(a6) move.l d0,d4 move.l d5,d1 jsr _LVOClose(a6) cmp.l #-1,d4 beq.s fail rts fail moveq #RETURN_FAIL,d7 end move.l a6,a1 move.l 4,a6 jsr _LVOCloseLibrary(a6) move.l a5,sp move.l d7,d0 rts dosname dc.b 'dos.library',0 execcmd dc.b '%s',10,0;---THIS LINE INSERTED IF 'EXECUTECMD' OPTION USED even start ;-- one for each file --------- file%k lea .f(pc),a3 jsr (a4) jmp .j .f dc.l .n,.d,.e-.d ; filename, data, length .n dc.b '%p%n',0 .d incbin '%f%n' .e dc.b 0 even .j ;----------- rts @endnode