The "File" Command |
This command adds a single file (no wildcards) to the MSI. It can add to a component or create a component for the file. The "Files" command uses this command to add files matching a wildcard you supply (optionally including all or part of a directory tree).
In general I use the "Files" command even for single files except when I need to do something it can't do (such as renaming files). Using the same command means I don't really have to remember the parameters of both!
Also have a look at the "Create Macro For Adding Files" tip for an example of one way of simplifying file addition.
I recommend that you read the "unversioned files" tip. You should at least consider this issue...
If you are adding a large number of files and this is a bit slow (probably the HTML generation) then you should have a look at the performance section! I recommend that you read the "Resource Life Cycle" section.
If MAKEMSI has problems and ignores (or doesn't find) files whose names or directories contain "international" characters then please see the documentation for the "MAKEMSI_MM_CODEPAGE" environment variable.
With the default MSI schema it can have a maximum of 32,767 files, however MAKEMSI will take a while to create this MSI and Windows Installer will be very slow to install and uninstall it. If you have large numbers of files I recommend you read the "performance" and "TABLES_FILE_SEQ_NUMBER_LIMIT" sections of this manual!
The command takes these parameters:
If this parameter's value contains a "\" then the directory part is (as you'd expect) the part before the last slash. If the value ends with a "\" character then you are supplying the installation directory without a filename (the destination and source filenames are identical).
You should only supply a "directory" if MAKEMSI is to build components for you (the "component" parameter resolves to "").
If this parameter is not supplied and if this command is nested between "component" and "/component" commands then the name of the "current" component is used (otherwise "" is used). The component's attributes control installation and uninstallation conditions and behaviour.
When creating components MAKEMSI will create as few components as possible (one per directory) except if the file extension is configured in the macro "FILE_EXTENSIONS_WHICH_NEED_OWN_COMPONENT", or this macro contains "*" (for all). To create components we must know which feature they belong to and if required you can pass Component parameters in the "OPTIONS4COMPONENT" parameter.
If this parameter is not supplied then the current 8.3 name of the source file is used if possible (its not available for "hard links" etc), otherwise a suitable 8.3 name is generated for you. (this also occurs if the file is being renamed). This process is simplistic but generally works, however if it fails then you may end up with 2 files with the same "8.3" name and this will result in "ICE30" validation errors.
This is one way of ensuring that an unversioned (or even versioned) file(s) you have included in the packages gets installed (its not left up to windows installer's versioning rules).
Note that "N" simply means don't use the "RemoveFile" command, it does not mean that the file will not be removed on uninstalled etc (see the "Resource Life Cycle" section if thats what you are interested in).
The default for this parameter can be set via the DEFAULT_FILE_REMOVE macro. The initial value is "N".
The default for this parameter can be set via the DEFAULT_FILE_ATTRIBUTES macro. The initial value for this is "Vital".
Available attributes (use space as a separator):
You should also remember that "component" attributes such as "NeverOverWrite" and "Permanent" are frequently useful.
If this parameter is supplied then the value overrides the default value which is based on the current nesting of the Cabinet and /Cabinet commands.
An error message will result if an unknown value is supplied.
The value of this parameter should be "" or one or more of the above attributes. It does not make much sense to have specified the same bits in the "Attributes" parameter as duplicated bits will always get set.
The default for this parameter can be set via the DEFAULT_FILE_ATTRIBUTES_TO_COPY macro. The initial value for this is "" (don't copy attributes).
If the value of this parameter is "" or begins with a question mark ("?") then MAKEMSI will assign a rowkey for you otherwise it will use the one you provided. If the value you provided started with a "?" then what follows is the name of a rexx variable which will hold the MAKEMSI assigned rowkey (for an example of this see "Add Fonts").
When this parameter is used on this command it is to add the current file to the exclude mask (which you will probably use in a subsequent "Files" command).
The default for this parameter can be set via the DEFAULT_FILE_SELFREGISTER macro. The initial value for this is "N".
The following shows the self registration related defaults:
#define? DEFAULT_FILE_SELFREGISTER N ;;N=Never, Y=Unordered, ?=Unordered Self register if binary supports it, else ordered self registration #define? FILE_AUTOMATIC_SELF_REGISTRATION_RECORD_NO Y ;;We are interested in when self registration was not done (html report) #define? FILE_AUTOMATIC_SELF_REGISTRATION_DETECT_ERROR_ACTION S ;;D=Die, S=Say & Ignore, I=Ignore (if not 'D' we assume testing will show up issues...) #define? FILE_AUTOMATIC_SELF_REGISTRATION_RECORD_NO_OK_VBEXP "<span title='We successfully determined that this file does not have self registration entry points!'>No</span>" #define? FILE_AUTOMATIC_SELF_REGISTRATION_RECORD_NO_ERR_VBEXP "<span title=""" & {$ErrDescVar} & """>No<font color=red>?</font></span>" #define? FILE_SUPPORT_WINDOWS_HARDLINKS_BUG Y ;;Windows file hardlink support flawed. #( ';' ;--- Semi colon (";") delimitered list of file extensions ---------------- #define? FILE_EXTENSIONS_WHICH_MAY_SELF_REGISTER .dll .ocx #)
The default for this parameter can be set via the DEFAULT_FILE_ROWKEY_CASE macro. The initial value for this is "" (don't adjust the case).
Note that Windows Installer does not support file hashes for versioned files, for this reason MAKEMSI will ignore this parameter for these files.
The default for this parameter can be set via the DEFAULT_FILE_WANT_FILEHASH macro. The initial value for this is "Y" (want a hash).
If a value was not passed then we will determine the version number and the value in the macro "FILE_VERSION_FOR_UNVERSIONED_FILES" (defaults to "") will be used if the file doesn't have a version. This allows unversioned files to be given a version number. I suggest using "<$ProductVersion>" as a suitable version number for unversioned files!
Note that tricking Windows Installer by supplying a version number for an unversioned file is one way of ensuring that an existing file on the file system is updated as required during an install, however it does have the disadvantage of forcing requests for the original source media during repairs etc. This method contradicts the Windows Installer documentation but it is documented in Microsoft's Windows Installer FAQ.
The Version information is placed into the HTML report by default.
If a non-blank value is supplied then it must be a date in the format "YYYY-MM-DD" (or "?" to use the current build date). It is a Microsoft restriction that "YYYY" be greater than or equal to "1980".
The default for this parameter can be set via the DEFAULT_FILE_DATE macro. The initial value is "".
If a non-blank value is supplied then it must be a time in the format "HH:MM:SS" (or "?" to use the current build date). Note that the seconds ("SS") value must be an even number.
The default for this parameter can be set via the DEFAULT_FILE_TIME macro. The initial value is "".
The default for this parameter can be set via the DEFAULT_FILE_OPTIONS4COMPONENT macro. The initial value for this is "".
If this includes component keypath information such as "CU='Y'" then you must also set the "FILE_GENERATED_COMPONENT_USE_FILE_AS_KEYPATH" option to "N" or the keypath information will be overwritten (a file keypath will be the result).
The default for this parameter can be set via the DEFAULT_FILE_DOCO macro. The initial value for this is "Y".
If you have a file containing the names of the files you'd like to include then have alook at the "Read a file List" tip.
SPECIAL PROCESSING |
MAKEMSI normally generates HTML documentation and has special exception code to allow you to add this documentation to your MSI. To add the documentation you must use the "RowKey" defined by the macro "FILE_HTMLRPT_ROWKEY", for this one instance the file is allowed to be missing (it has not yet been generated) and some details will be filled in at the "compile" stage.
Main File Related Options |
Please see the "options for commands" section of the manual.
#define? DEFAULT_FILE_WANT_FILEHASH T ;;Generate MD5 (Y=YES, N=NO, T=TRY). MD5 needs Windows Installer 2.0+ #define? DEFAULT_FILE_ATTRIBUTES Vital ;;Only use if user did not supply #define? DEFAULT_FILE_ATTRIBUTES_TO_COPY ;;Choose one or more from hidden/system/readonly #define? DEFAULT_FILE_LANG_WHEN_GETLANGUAGE_FAILS 1033 ;;Can be "" #define? DEFAULT_FILE_ACCESS #define? DEFAULT_FILE_REMOVE N ;;Don't remove files by default! #define? DEFAULT_FILE_DATE ;;""= file date or date in "YYYY-MM-DD" (exactly 10 characters) #define? DEFAULT_FILE_TIME ;;""= file time or time in "HH:mm:SS" (exactly 8 characters and seconds even) #define? DEFAULT_FILE_DOCO Y ;;"N" = Don't add to doco (by default) #define? DEFAULT_FILE_OPTIONS4COMPONENT ;;Any options for autocreated components #define? DEFAULT_FILE_OPTION_MAKE_REMOVE_DIRECTORIES Y ;;Now make/remove directories by default #define? FILE_HTMLRPT_INSTALLTIME_COMMENT_TEXT * ;;What the user sees #define? FILE_HTMLRPT_INSTALLTIME_COMMENT_HTML <span title='The install time of the file will be "{?}"'><font color=red><$FILE_HTMLRPT_INSTALLTIME_COMMENT_TEXT></font></span> ;;Don't use Double quotes and ONLY the text in the "FILE_HTMLRPT_INSTALLTIME_COMMENT_TEXT" macro should be visible to user (or sorting won't work correctly)!!! #define? FILE_GENERATED_COMPONENT_PREFIX c ;;Begins any components generated by the "file(s)" commands, followed by unique number ("" means don't add unique prefix) #define? FILE_GENERATED_COMPONENT_USE_FILE_AS_KEYPATH Y ;;Must be "Y" unless you have set a keypath in the "Options4Component" parameter (in which case should be "N")! #define? FILE_GENERATED_COMPONENT_MAX_LENGTH <$TABLES_LNG_COMPONENT_COLUMN> ;;Should be shorter than or equal to value in "TABLES_LNG_COMPONENT_COLUMN" (see doco for error code 2716) #( ';' ;--- Semi colon (";") delimitered list of file extensions ---------------- #define? FILE_EXTENSIONS_WHICH_NEED_OWN_COMPONENT ;;"*" means all .exe .dll .ocx .hlp .chm #) #define? FILE_COMMAND_ALLOWED ;;If not blank then not allowed and is the error message. You can use "{NL}" to represent newlines #define? FILE_VERSION_FOR_UNVERSIONED_FILES #define? DEFAULT_FILE_ROWKEY_CASE ;;Can be "" or "L" or "U" #define? DEFAULT_FILE_ROWKEY_MAXLNG <$TABLES_LNG_FILE_COLUMN>-4 ;;0 = no restriction (this limit is WITHOUT any possible number added to make unique!) #define? FILE_HTMLRPT_HR <$SUNDRY_HTMLRPT_HR> #define? FILE_HTMLRPT_ROWKEY MAKEMSI_Documentation ;;Name of special case which does not exist when code generated! #define? FILE_HTMLRPT_MAX_EXTENSION_WIDTH 7 #define? FILE_STYLE_TEXT_ERROR color:red #define? FILE_STYLE_TEXT_OK color:green #define? FILE_VERIFY_STYLE_FILENAME_DEFAULT_LOCN color:blue #define? FILE_VERIFY_OUTPUT_BACKGROUND_COLOR #dfdfdf #define? FILE_VERIFY_SHOW_COMPONENT_OK_MESSAGE_WHEN_FILES_ALSO_OK N #define? FILE_VERIFY_ATTRIBUTE_SET.H <b>H</b> #define? FILE_VERIFY_ATTRIBUTE_SET.R <b>R</b> #define? FILE_VERIFY_ATTRIBUTE_SET.S <b>S</b> #define? FILE_VERIFY_ATTRIBUTE_RESET.H h #define? FILE_VERIFY_ATTRIBUTE_RESET.R r #define? FILE_VERIFY_ATTRIBUTE_RESET.S s #( '<?NewLine>' #define? FILE_STYLES .FileCmtPlus {font-size:9pt;} .FileCmtName {<$HTMLRPT_STYLE_VALUES_KEY>} .FileCmtValue {<$HTMLRPT_STYLE_VALUES_VALUE>} .FileCmtSFI {color:maroon} <$FILE_STYLES_VERIFY> <$FILE_STYLES_VERIFY_COMPONENT_CHECKS> #) #( '<?NewLine>' #define? FILE_STYLES_VERIFY .FileVerify_DoesNotExist {<$FILE_STYLE_TEXT_ERROR>} .FileVerify_FileNameDefault {<$FILE_VERIFY_STYLE_FILENAME_DEFAULT_LOCN>} .FileVerify_CantAccess {<$FILE_STYLE_TEXT_ERROR>} .FileVerify_OK {<$FILE_STYLE_TEXT_OK>} .FileVerify_MisMatch {<$FILE_STYLE_TEXT_ERROR>} .FileVerifyNoActiveX {<$FILE_STYLE_TEXT_ERROR>} .FileVerifyProductErr {<$FILE_STYLE_TEXT_ERROR>} .FileVerifyProductOK {<$FILE_STYLE_TEXT_OK>} #) #( '<?NewLine>' #define? FILE_STYLES_VERIFY_COMPONENT_CHECKS .FileVerify_ComponentUnmanaged {} .FileVerify_ComponentNotInstalledAndFileDoesntExist {<$FILE_STYLE_TEXT_OK>} .FileVerify_ComponentInstalledAndFileOk {<$FILE_STYLE_TEXT_OK>} .FileVerify_GuidUnknown {<$FILE_STYLE_TEXT_ERROR>} .FileVerify_ComponentNotInstalledButFileOk {<$FILE_STYLE_TEXT_ERROR>} .FileVerify_ComponentNotInstalledAndFileDoesntMatch {<$FILE_STYLE_TEXT_ERROR>} .FileVerify_ComponentInstalledButFileDoesntMatch {<$FILE_STYLE_TEXT_ERROR>} #)
EXAMPLE #1 |
;--- Set up some default file comments -------------------------------------- <$FileComment ".txt" Comment="Text file"> <$FileComment ".exe" Comment="Executable binary file"> <$FileComment ".dll" Comment="Dynamic Link Library"> <$FileComment ".htm" Comment="HTML"> <$FileComment ".html" Comment="HTML"> <$FileComment ".jpg" Comment="Graphics file"> <$FileComment ".gif" Comment="Graphics file"> <$FileComment ".asp" Comment="Active Server Page"> ;--- Create component and add some files ------------------------------------ <$Component "Fred" Create="Y" Directory_="INSTALLDIR"> <$File Source="A file I Installed.txt"> <$File Source="..\X\Another.txt"> <$File Source="D:\DBAREIS\tools\where.exe"> <$File Source="Slides.ppt" Destination="Slides.pps"> ;;Convert powerpoint to "Power Point Show" #( ;--- This source file has read-only set! ----------------------------- <$File Source="c:\winnt\welc.exe" Comment=^This file has the read-only attribute set. It should get copied to the file table attributes!^ CopyAttributes="ReadOnly Hidden" > #) ;--- Add some other files (demo default comment) ------------------------- <$FileComment Comment="File required by xyz"> <$File Source="required.exe"> <$FileComment Comment=""> <$File Source="NoDefaultCommentForThisFile.txt"> <$/FileComment> <$File Source="required.dll"> <$/FileComment> <$/Component>
EXAMPLE #2 - Set File Access |
<$Access "Admin(complete)" Users="Administrators SYSTEM" Access="GENERIC_ALL"> <$Access "AuthenticatedUsers(ReadOnly)" Users=^'Authenticated Users'^ Access="GENERIC_READ GENERIC_EXECUTE"> #( <$File Access="Admin(complete) AuthenticatedUsers(ReadOnly)" Source="<$SOURCE_DIR>\SomeFile.ini" Destination="[INSTALLDIR]\SomeFile.ini" Options4Component=^ComponentId=''^ ;;Don't want repair or uninstall of this file EXLIST="SomeFile.ini" > #)