NSIS Wiki - User contributions [en]

Repair path names with ..

2006-10-01T21:11:02Z

Animaether: added third note and function-using section

you have a path with relative path parts, such as
<highlight-nsis>
\\ ; does nothing
\.\ ; stay in same folder
\..\ ; go up a folder
</highlight-nsis>

And you need the absolute path, then you can use the "GetFullPathName" command in NSIS to get the absolute path. For example:
<highlight-nsis>
Section Test
GetFullPathName $0 "c:\program files\myApp\somedir\subdir\..\somefile.ext"
; $0 will now contain "c:\program files\myApp\somedir\somefile.ext"
SectionEnd
</highlight-nsis>

Note 1: if you specify a filename, that file has to exist or the result is null.It is therefore recommended that if you need the absolute path without necessarily having the file in existence, that you strip the filename from the path.

Note 2: this command is limited to a 256-character string, even if the resulting absolute path is shorter than 256 characters.

Note 3: if the string being fed does not start with an absolute reference, it will be treated as if relative to the current working folder, and the absolute path result will reflect this. E.g.
<highlight-nsis>
Section Test
GetFullPathName $0 "FooBar\"
; $0 may now contain "c:\test\Foobar\" if the installer was executed in "c:\test\"
SectionEnd
</highlight-nsis>

If any of the above notes may preclude you from using this Command, try the below Function instead.

<highlight-nsis>
Section "Rel2Abs"
Push "c:\Alpha\\\Bravo\\Charlie..charles\\.\delta\\echo\\..\..\foxtrot\\..\Golf\\.\Hotel\\.\india\\..\\\\juliet\\..\kilo\\\..\Li.....ma\\.\..Mike\\\November\\.\oscar\\..\Papa\\\Quebec..\\\\\\\\Romeo\\sierra\\..\tang.o\\uniform\\victor\\..\whiskey\\..\\x-ray\\yankee\\..\..\.\..\..\Zu.lu\\file.ext"
Call Abs2Rel
Pop $0
MessageBox MB_OK "Expected:$\tc:\Alpha\Bravo\Charlie..charles\Golf\Hotel\Li.....ma\..Mike\November\Papa\Quebec..\Romeo\Zu.lu\file.ext$\r$\nResult:$\t$\t$0"
SectionEnd

Function Abs2Rel
; Stack -> ; <relative path> ; This and the stuff in the column below is just to keep track of the stack before and after the function so that it's clean at the end.
Exch $R0 ; R0 ; $R0 now holds the relative path
Push $0 ; 0 R0 ; $0 will hold the absolute path as it is being built
Push $1 ; 1 0 R0 ; $1 will hold the length of the relative path
Push $2 ; 2 1 0 R0 ; $2 will hold a counter for running along the path
Push $3 ; 3 2 1 0 R0 ; $3 will hold a substring of the paths to test against

StrCpy $0 $R0 1 0 ; Start by getting the first character of the relative path into the absolute path var
StrLen $1 $R0 ; Get the length of the relative path
StrCpy $2 0 ; And start the counter off at zero

; example path at this point
; c:\Alpha\\\Bravo\\Charlie..charles\\.\delta\\echo\\..\..\foxtrot\\..\Golf\\.\Hotel\\.\india\\..\\\\juliet\\..\kilo\\\..\Li.....ma\\.\..Mike\\\November\\.\oscar\\..\Papa\\\Quebec..\\\\\\\\Romeo\\sierra\\..\tang.o\\uniform\\victor\\..\whiskey\\..\\x-ray\\yankee\\..\..\.\..\..\Zu.lu\\file.ext

; double ; This section will get rid of all double backslashes.
_loop_double: ; top of the loop
IntOp $2 $2 + 1 ; increase the counter
IntCmp $2 $1 0 0 _sameDir ; if the counter exceeds the relative path's length, move on
StrCpy $3 $R0 2 $2 ; get two characters from the relative pah, starting at the position of the counter
StrCmp $3 "\\" _loop_double ; if it's a double backslash, just go back to the top of the loop
StrCpy $3 $R0 1 $2 ; otherwise, get a single character from the relative path, starting at the position of the counter
StrCpy $0 "$0$3" ; and add that character to the absolute path being built
goto _loop_double ; then go back to the top of the loop

; example path at this point
; c:\Alpha\Bravo\Charlie..charles\.\delta\echo\..\..\foxtrot\..\Golf\.\Hotel\.\india\..\juliet\..\kilo\..\Li.....ma\.\..Mike\November\.\oscar\..\Papa\Quebec..\Romeo\sierra\..\tang.o\uniform\victor\..\whiskey\..\x-ray\yankee\..\..\.\..\..\Zu.lu\file.ext

_sameDir: ; This section will get rid of all \.\ occurrences.
StrCpy $R0 $0 ; First, copy the working copy absolute path into the relative path var. We won't need the original anymore.
StrCpy $0 $R0 1 0 ; Again, get the first character
StrLen $1 $R0 ; Get the length
StrCpy $2 0 ; Start the counter at zero

_loop_sameDir: ; top of the loop
IntOp $2 $2 + 1 ; increase the counter
IntCmp $2 $1 0 0 _dirup ; if the counter exceeds the relative path's length, move on
StrCpy $3 $R0 3 $2 ; get three characters from the relative path, starting at the position of the counter
StrCmp $3 "\.\" 0 +3 ; if that's \.\ , then we'll have to...
IntOp $2 $2 + 1 ; increase the counter by 1 to stop going over the period.
goto _loop_sameDir ; and go back to the top of the loop

StrCpy $3 $R0 1 $2 ; otherwise, get a single character from the relative path, starting at the position of the counter
StrCpy $0 "$0$3" ; and add that character to the absolute path being built
goto _loop_sameDir ; then go back to the top of the loop

; example path at this point
; c:\Alpha\Bravo\Charlie..charles\delta\echo\..\..\foxtrot\..\Golf\Hotel\india\..\juliet\..\kilo\..\Li.....ma\..Mike\November\oscar\..\Papa\Quebec..\Romeo\sierra\..\tang.o\uniform\victor\..\whiskey\..\x-ray\yankee\..\..\..\..\Zu.lu\file.ext

_dirup: ; This section will deal with \..\ occurrences, removing them -and- the parent folder
StrCpy $R0 $0 ; this
StrCpy $0 $R0 1 0 ; should
StrLen $1 $R0 ; look
StrCpy $2 0 ; familar
Push "Rel2Abs" ; push a tag to the top of the stack. We'll be doing some popping further down and want to make sure we don't exceed the stack/etc.
_loop_dirup: ; more
IntOp $2 $2 + 1 ; familiar
IntCmp $2 $1 0 0 _loop_cleanStack ; things

StrCpy $3 $R0 1 $2 ; get a single character from the relative path, starting at the position of the counter
StrCpy $0 "$0$3" ; add that character to the absolute path being built
StrCmp $3 "\" 0 _loop_dirup ; if the character was a backslash, continue - otherwise, go back to the top of the stack
StrCpy $3 $0 4 -4 ; get -four- characters from the relative path, starting at the position of the counter
StrCmp $3 "\..\" 0 _subDir ; if those four were \..\, continue to process this as going up a dir - otherwise we're just going down a dir
Pop $0 ; Get the top of the stack into our absolute path. Say the stack looked like "c:\test\", "c:\test\hello\", and we just encountered "c:\test\hello\,,\", then this will be "c:\test\hello\"
StrCmp $0 "Rel2Abs" _error ; If the value is our tag, then we just went up the stack too far, and the path this function was fed is invalid, so error out.
Pop $0 ; Get the top of the stack in our absolute path. Going with the previous example, this value will now be "c:\test\", and as such as we just moved up a dir.
StrCmp $0 "Rel2Abs" _error ; If the value is our tag, then we just went up the stack too far, and the path this function was fed is invalid, so error out.
Push $0 ; Push this value back onto the stack because we'll need it on there.
goto _loop_dirup ; And go back to the top of the loop
_subDir: ; Otherwise we went down a dir
Push $0 ; So we'll just push this absolute path so far onto the stacak.
goto _loop_dirup ; and go back to the top of the loop

; example path at this point
; c:\Alpha\Bravo\Charlie..charles\Golf\Hotel\Li.....ma\..Mike\November\Papa\Quebec..\Romeo\Zu.lu\file.ext

_loop_cleanStack: ; At this point we already have our relative path - but there's a bunch of bits stuck on the stack
Pop $1 ; So we pop the stack
StrCmp $1 "Rel2Abs" 0 _loop_cleanStack ; and as long as the value isn't our tag, we'll keep on popping

StrCpy $R0 $0 ; Once it is, we're done entirely - copy the absolute path into $R0 for end-function stack purposes
goto _end ; goto the end (skip over the error)

_error: ; This is where we went if the path being fed was mangled or we ran into our tag early otherwise
StrCpy $R0 "-1" ; we'll just set the return value to -1

_end: ; end of the function, time to restore variables off the stack and push the result onto it.
; Stack -> ; 3 2 1 0 R0
Pop $3 ; 2 1 0 R0
Pop $2 ; 1 0 R0
Pop $1 ; 0 R0
Pop $0 ; R0
Exch $R0 ; <absolute path>
FunctionEnd
</highlight-nsis>

Talk:Repair path names with ..

2006-10-01T21:04:25Z

Animaether:

Kichik, GetFullPathname was failing in an instance I was using it in - couldn't for the life of me figure out why. Found two causes and documented them here, also provided the Function I'm now using. [[User:Animaether|Animaether]] 14:04, 1 October 2006 (PDT)

Repair path names with ..

2006-10-01T21:03:05Z

Animaether: forgot to login, fixed formatting in top

you have a path with relative path parts, such as
<highlight-nsis>
\\ ; does nothing
\.\ ; stay in same folder
\..\ ; go up a folder
</highlight-nsis>

And you need the absolute path, then you can use the "GetFullPathName" command in NSIS to get the absolute path. For example:
<highlight-nsis>
Section Test
GetFullPathName $0 "c:\program files\myApp\somedir\subdir\..\somefile.ext"
; $0 will now contain "c:\program files\myApp\somedir\somefile.ext"
SectionEnd
</highlight-nsis>

Please note that if you specify a filename, that file has to exist or the result is null. It is therefore recommended that if you need the absolute path without necessarily having the file in existence, that you strip the filename from the path.

Please also note that this command is limited to a 256-character string, even if the resulting absolute path is shorter than 256 characters.

If you have a longer string, you may try the below function.

<highlight-nsis>
Function Abs2Rel
; Stack -> ; <relative path> ; This and the stuff in the column below is just to keep track of the stack before and after the function so that it's clean at the end.
Exch $R0 ; R0 ; $R0 now holds the relative path
Push $0 ; 0 R0 ; $0 will hold the absolute path as it is being built
Push $1 ; 1 0 R0 ; $1 will hold the length of the relative path
Push $2 ; 2 1 0 R0 ; $2 will hold a counter for running along the path
Push $3 ; 3 2 1 0 R0 ; $3 will hold a substring of the paths to test against

StrCpy $0 $R0 1 0 ; Start by getting the first character of the relative path into the absolute path var
StrLen $1 $R0 ; Get the length of the relative path
StrCpy $2 0 ; And start the counter off at zero

; example path at this point
; c:\Alpha\\\Bravo\\Charlie..charles\\.\delta\\echo\\..\..\foxtrot\\..\Golf\\.\Hotel\\.\india\\..\\\\juliet\\..\kilo\\\..\Li.....ma\\.\..Mike\\\November\\.\oscar\\..\Papa\\\Quebec..\\\\\\\\Romeo\\sierra\\..\tang.o\\uniform\\victor\\..\whiskey\\..\\x-ray\\yankee\\..\..\.\..\..\Zu.lu\\file.ext

; double ; This section will get rid of all double backslashes.
_loop_double: ; top of the loop
IntOp $2 $2 + 1 ; increase the counter
IntCmp $2 $1 0 0 _sameDir ; if the counter exceeds the relative path's length, move on
StrCpy $3 $R0 2 $2 ; get two characters from the relative pah, starting at the position of the counter
StrCmp $3 "\\" _loop_double ; if it's a double backslash, just go back to the top of the loop
StrCpy $3 $R0 1 $2 ; otherwise, get a single character from the relative path, starting at the position of the counter
StrCpy $0 "$0$3" ; and add that character to the absolute path being built
goto _loop_double ; then go back to the top of the loop

; example path at this point
; c:\Alpha\Bravo\Charlie..charles\.\delta\echo\..\..\foxtrot\..\Golf\.\Hotel\.\india\..\juliet\..\kilo\..\Li.....ma\.\..Mike\November\.\oscar\..\Papa\Quebec..\Romeo\sierra\..\tang.o\uniform\victor\..\whiskey\..\x-ray\yankee\..\..\.\..\..\Zu.lu\file.ext

_sameDir: ; This section will get rid of all \.\ occurrences.
StrCpy $R0 $0 ; First, copy the working copy absolute path into the relative path var. We won't need the original anymore.
StrCpy $0 $R0 1 0 ; Again, get the first character
StrLen $1 $R0 ; Get the length
StrCpy $2 0 ; Start the counter at zero

_loop_sameDir: ; top of the loop
IntOp $2 $2 + 1 ; increase the counter
IntCmp $2 $1 0 0 _dirup ; if the counter exceeds the relative path's length, move on
StrCpy $3 $R0 3 $2 ; get three characters from the relative path, starting at the position of the counter
StrCmp $3 "\.\" 0 +3 ; if that's \.\ , then we'll have to...
IntOp $2 $2 + 1 ; increase the counter by 1 to stop going over the period.
goto _loop_sameDir ; and go back to the top of the loop

StrCpy $3 $R0 1 $2 ; otherwise, get a single character from the relative path, starting at the position of the counter
StrCpy $0 "$0$3" ; and add that character to the absolute path being built
goto _loop_sameDir ; then go back to the top of the loop

; example path at this point
; c:\Alpha\Bravo\Charlie..charles\delta\echo\..\..\foxtrot\..\Golf\Hotel\india\..\juliet\..\kilo\..\Li.....ma\..Mike\November\oscar\..\Papa\Quebec..\Romeo\sierra\..\tang.o\uniform\victor\..\whiskey\..\x-ray\yankee\..\..\..\..\Zu.lu\file.ext

_dirup: ; This section will deal with \..\ occurrences, removing them -and- the parent folder
StrCpy $R0 $0 ; this
StrCpy $0 $R0 1 0 ; should
StrLen $1 $R0 ; look
StrCpy $2 0 ; familar
Push "Rel2Abs" ; push a tag to the top of the stack. We'll be doing some popping further down and want to make sure we don't exceed the stack/etc.
_loop_dirup: ; more
IntOp $2 $2 + 1 ; familiar
IntCmp $2 $1 0 0 _loop_cleanStack ; things

StrCpy $3 $R0 1 $2 ; get a single character from the relative path, starting at the position of the counter
StrCpy $0 "$0$3" ; add that character to the absolute path being built
StrCmp $3 "\" 0 _loop_dirup ; if the character was a backslash, continue - otherwise, go back to the top of the stack
StrCpy $3 $0 4 -4 ; get -four- characters from the relative path, starting at the position of the counter
StrCmp $3 "\..\" 0 _subDir ; if those four were \..\, continue to process this as going up a dir - otherwise we're just going down a dir
Pop $0 ; Get the top of the stack into our absolute path. Say the stack looked like "c:\test\", "c:\test\hello\", and we just encountered "c:\test\hello\,,\", then this will be "c:\test\hello\"
StrCmp $0 "Rel2Abs" _error ; If the value is our tag, then we just went up the stack too far, and the path this function was fed is invalid, so error out.
Pop $0 ; Get the top of the stack in our absolute path. Going with the previous example, this value will now be "c:\test\", and as such as we just moved up a dir.
StrCmp $0 "Rel2Abs" _error ; If the value is our tag, then we just went up the stack too far, and the path this function was fed is invalid, so error out.
Push $0 ; Push this value back onto the stack because we'll need it on there.
goto _loop_dirup ; And go back to the top of the loop
_subDir: ; Otherwise we went down a dir
Push $0 ; So we'll just push this absolute path so far onto the stacak.
goto _loop_dirup ; and go back to the top of the loop

; example path at this point
; c:\Alpha\Bravo\Charlie..charles\Golf\Hotel\Li.....ma\..Mike\November\Papa\Quebec..\Romeo\Zu.lu\file.ext

_loop_cleanStack: ; At this point we already have our relative path - but there's a bunch of bits stuck on the stack
Pop $1 ; So we pop the stack
StrCmp $1 "Rel2Abs" 0 _loop_cleanStack ; and as long as the value isn't our tag, we'll keep on popping

StrCpy $R0 $0 ; Once it is, we're done entirely - copy the absolute path into $R0 for end-function stack purposes
goto _end ; goto the end (skip over the error)

_error: ; This is where we went if the path being fed was mangled or we ran into our tag early otherwise
StrCpy $R0 "-1" ; we'll just set the return value to -1

_end: ; end of the function, time to restore variables off the stack and push the result onto it.
; Stack -> ; 3 2 1 0 R0
Pop $3 ; 2 1 0 R0
Pop $2 ; 1 0 R0
Pop $1 ; 0 R0
Pop $0 ; R0
Exch $R0 ; <absolute path>
FunctionEnd
</highlight-nsis>

Repair path names with ..

2006-09-28T22:22:13Z

Animaether:

Seeing as how this page didn't exist yet, but the topic did, hopefully somebody else can clean it up...

Below is a very naive piece of code, which uses LogicLib a bit to keep things sane. DON'T USE THIS CODE :D
(not until somebody cleans it up anyway)
<highlight-nsis>
Section "Bladeebla"
StrCpy $R0 "C:\folder\subfolder\.\anotherfolder\..\someotherfolder\somefile.ext"
StrCpy $4 $R0 1 0
StrLen $1 $R0
StrCpy $2 0
Push "RelAbs"
_loop:
IntOp $2 $2 + 1
${If} $2 > $1
goto _end
${EndIf}
StrCpy $0 $R0 3 $2
${If} $0 == "..\"
Pop $4
Pop $4
IntOp $2 $2 + 2
${ElseIf} $0 == "\.\"
IntOp $2 $2 + 1
${Else}
StrCpy $3 $R0 1 $2
StrCpy $4 "$4$3"
${If} $3 == "\"
Push $4
${EndIf}
${EndIf}
goto _loop
_end:

_loop2:
Pop $0
${If} $0 == "RelAbs"
goto _end2
${EndIf}
goto _loop2
_end2:

MessageBox MB_OK "$R0$\r$\n$4"
SectionEnd
</highlight-nsis>

This will display a messagebox with:
C:\folder\subfolder\.\anotherfolder\..\someotherfolder\somefile.ext
C:\folder\subfolder\someotherfolder\somefile.ext

Note that instead of lots of string manipulations, this code is either lazy or smart, depending on how you look at it. Everytime a "\.\" is encountered, it ignores it. Everytime a "..\" is encountered, it also ignores it, and Pops the currently collected path off the stack, twice, to get back to what the collected path was before the parent folder was added.
If a "\" is encountered not as part of the above two, the currently collected path is pushed to the stack, effectively pushing the path with each folder encountered to the stack.
Then at the end the stack is cleaned up by popping off until "RelAbs" is the value popped.

Please note that this means you can't feed it paths like "..\whatever" because it doesn't know where to start in. It also doesn't deal with forward slashes "/". It doesn't bother cleaning up "\\", it fails when you've got "A\B\C\D\..\..\" (returning "A\") etc. So the above code really is quite naive, should be cleaned up, etc. but may be a good starting point as it doesn't do insane things with strings using a ton of variables.

Repair path names with ..

2006-09-28T22:19:22Z

Animaether:

Seeing as how this page didn't exist yet, but the topic did, hopefully somebody else can clean it up...

Below is a very naive piece of code, which uses LogicLib a bit to keep things sane.
<highlight-nsis>
Section "Bladeebla"
StrCpy $R0 "C:\folder\subfolder\.\anotherfolder\..\someotherfolder\somefile.ext"
StrCpy $4 $R0 1 0
StrLen $1 $R0
StrCpy $2 0
Push "RelAbs"
_loop:
IntOp $2 $2 + 1
${If} $2 > $1
goto _end
${EndIf}
StrCpy $0 $R0 3 $2
${If} $0 == "..\"
Pop $4
Pop $4
IntOp $2 $2 + 2
${ElseIf} $0 == "\.\"
IntOp $2 $2 + 1
${Else}
StrCpy $3 $R0 1 $2
StrCpy $4 "$4$3"
${If} $3 == "\"
Push $4
${EndIf}
${EndIf}
goto _loop
_end:

_loop2:
Pop $0
${If} $0 == "RelAbs"
goto _end2
${EndIf}
goto _loop2
_end2:

MessageBox MB_OK "$R0$\r$\n$4"
SectionEnd
</highlight-nsis>

This will display a messagebox with:
C:\folder\subfolder\.\anotherfolder\..\someotherfolder\somefile.ext
C:\folder\subfolder\someotherfolder\somefile.ext

Note that instead of lots of string manipulations, this code is either lazy or smart, depending on how you look at it. Everytime a "\.\" is encountered, it ignores it. Everytime a "..\" is encountered, it also ignores it, and Pops the currently collected path off the stack, twice, to get back to what the collected path was before the parent folder was added.
If a "\" is encountered not as part of the above two, the currently collected path is pushed to the stack, effectively pushing the path with each folder encountered to the stack.
Then at the end the stack is cleaned up by popping off until "RelAbs" is the value popped.

Please note that this means you can't feed it paths like "..\whatever" because it doesn't know where to start in. It also doesn't deal with forward slashes "/". It doesn't bother cleaning up "\\", etc. So the above code really is quite naive, should be cleaned up, etc. but may be a good starting point as it doesn't do insane things with strings using a ton of variables.

Macro vs Function

2006-09-16T16:01:53Z

Animaether: PSx, added Conclusion section

{{PageAuthor|Animaether}}
Macros and Functions in NSIS are powerful tools to help make coding your installer easier and more flexible. They can also be very powerful tools, allowing you to extend the NSIS scripting language to an extent - LogicLib is a great example of this.

= Definitions =
== Macros ==
From the NSIS help file: "Macros are used to insert code at compile time, depending on defines and using the values of the defines. The macro's commands are inserted at compile time. This allows you to write a general code only once and use it a lot of times but with a few changes."

If you are new to macros in any scripting language, then this may sound a bit confusing. Let's go through a few examples to show what the above means.

"Macros are used to insert code at compile time"

What this means is that the code you define in a macro will simply be inserted at the location of your !insertmacro, as if copy/pasted, when you compile your installer script.

Example 1.1.1
<highlight-nsis>
!macro Hello
DetailPrint "Hello world"
!macroend

Section Test
!insertmacro Hello
SectionEnd
</highlight-nsis>

Could be seen as just:

Example 1.1.2
<highlight-nsis>
Section Test
DetailPrint "Hello world"
SectionEnd
</highlight-nsis>

The above is obviously just a simple example with a single line and really wouldn't be a good use of macros. But if you have multiple lines of code that you may have to use over and over again, it may be a good idea to start using a macro for it; it allows you to just make the any changes once in the macro, and it will automatically be changed anywhere you insert it. It also just makes your code look a lot cleaner (a single !insertmacro line vs perhaps a dozen lines) which makes it a lot easier to follow and edit.

"depending on defines and using the values of the defines"

That bit is most likely to sound confusing, but gets a little more clear once you read the definition of macros in another section of the NSIS help:

"macro definitions can have one or more parameters defined. The parameters may be accessed the same way a !define would (e.g. ${PARMNAME}) from inside the macro."

If you are familiar with scripting in other languages, this may sound familiar to you, except in the context of functions - but please do not mix this up with Functions as they exist in the NSIS language.. we'll get to those later.

What the above means is that you can have a macro take parameters, or arguments, and use those within the macro:

Example 1.1.3
<highlight-nsis>
!macro Hello What
DetailPrint "Hello ${What}"
!macroend

Section Test
!insertmacro Hello "World"
!insertmacro Hello "Tree"
!insertmacro Hello "Flower"
SectionEnd
</highlight-nsis>

Could be seen as just:

Example 1.1.4
<highlight-nsis>
Section Test
DetailPrint "Hello World"
DetailPrint "Hello Tree"
DetailPrint "Hello Flower"
SectionEnd
</highlight-nsis>

However, you only needed a single macro definition to get these three different results. Let's take a more complex example, straight from the NSIS Help. In NSIS, a Function can only be specified as being for the Installer, or the Uninstaller (prefixed by "un."). The reason for this is that it allows the compiler to make a smaller Uninstaller if it does not need the Installer's functions, and vice-versa. However, sometimes you may have a function that both the Installer and the Uninstaller require. You could then code the Function twice:

Example 1.1.5
<highlight-nsis>
Function SomeFunc
; Lots of code here
FunctionEnd

Function un.SomeFunc
; Lots of code here
FunctionEnd
</highlight-nsis>
However, as it should be apparent, if there's lots of code involved you have two separate areas where you have to make code changes, your code looks less clean, etc.

With the use of macros, this can easily be resolved by writing a macro around the function that simply adds the "un." prefix when requested:

Example 1.1.6
<highlight-nsis>
!macro SomeFunc un
Function ${un}SomeFunc
; lots of code here
FunctionEnd
!macroend
!insertmacro SomeFunc ""
!insertmacro SomeFunc "un."
</highlight-nsis>

The above will then be written out as example 1.1.5, but now you only have a single portion of code to maintain.

For more information on this specific topic, see: [[Sharing functions between Installer and Uninstaller]]

== Functions ==
Let's start again with what the NSIS Help file says on them:

"Functions are similar to Sections in that they contain zero or more instructions."

Let's try a different definition. Functions are like macros, except that the code does -not- actually get inserted or copy/pasted, if you will, when compiling. The compiled code only exists just once in your final installer.

A Function use equivalent to the Macro example 1.1.1 would be:

Example 1.2.1
<highlight-nsis>
Function Hello
DetailPrint "Hello world"
FunctionEnd

Section Test
Call Hello
SectionEnd
</highlight-nsis>

You also cannot pass parameters/arguments to Functions as easily as you can with Macros. I.e. the following is NOT a valid code equivalent of Example 1.1.3:

Example: 1.2.2
<highlight-nsis>
Function Hello What
DetailPrint "Hello ${What}"
FunctionEnd

Section Test
Call Hello "World"
Call Hello "Tree"
Call Hello "Flower"
SectionEnd
</highlight-nsis>

You could, of course, try to take a page out of the earlier installer/uninstaller book and wrap the function in a macro:

Example 1.2.3
<highlight-nsis>
!macro Hello What
Function Hello
DetailPrint "Hello ${What}"
FunctionEnd
!macroend

Section Test
!insertmacro Hello "World"
SectionEnd
</highlight-nsis>
But this is -also- invalid code, as the code would end up having a Function definition within a section, which is not allowed:

Example 1.2.4
<highlight-nsis>
Section Test
Function Hello
DetailPrint "Hello ${What}"
FunctionEnd
SectionEnd
</highlight-nsis>

( even if Function definitions were allowed within Sections, keep in mind that you would have more than a single Function named "Hello" - which is also not allowed )

Instead, passing parameters/arguments to Functions is typically done through variables...

Example 1.2.5
<highlight-nsis>
var myVar

Function Hello
DetailPrint "Hello $myVar"
FunctionEnd

Section Test
StrCpy $myVar "World"
Call Hello
SectionEnd
</highlight-nsis>

...or, more commonly, the stack (to save memory used by variables)

Example 1.2.6
<highlight-nsis>
Function Hello
Exch $0
DetailPrint "Hello $0"
Pop $0
FunctionEnd

Section Test
Push "World"
Call Hello
SectionEnd
</highlight-nsis>

Which ends up acting as (but please note that the code is not actually inserted as such!):

Example 1.2.7
<highlight-nsis>
Section Test
Push "World"
; At this point, the stack looks like the following (top is left, bottom is right)
; :: "World" -rest of the stack, if anything-
Exch $0
; At this point the old value of $0 is now at the top of the stack, while "World" is copied into variable $0
; :: old$0 -rest of the stack, if anything-
DetailPrint "Hello World"
Pop $0
; At this point the old value of $0 is restored, and the stack just looks like the following:
; :: -rest of the stack, if anything-
</highlight-nsis>

Functions can either clear the stack relevant to the function, as in the above, or they can leave an item on the stack for use after the function.

Example 1.2.8
<highlight-nsis>
Function isDir
Exch $0
IfFileExists "$0\*.*" _dir _notdir
_dir:
StrCpy $0 "true"
return
_notdir:
StrCpy $0 "false"
FunctionEnd

Section Test
Push "some path on your drive"
Call isDir
Pop $0
SectionEnd
</highlight-nsis>

Where in the above code, after the call to "isDir", $0 contains "true" if the path was a directory, and "false" if not.

= Hybrid =
Mainly because of the fact that you can't easily pass parameters to Functions, many users adopt a hybrid approach employing both macros -and- functions, and a little bit of a define. (a define just allows you to say that e.g. "NSIS" means "Nullsoft Scriptable Install System" without having to write out as much).

Example 2.1
<highlight-nsis>
!define writeFile "!insertmacro writeFile"

!macro writeFile File String
Push ${File}
Push ${String}
Call writeFile
!macroend

Function writeFile
; Stack: <file> <string>
ClearErrors
Exch $0 ; Stack: $0 <string>
Exch ; Stack: <string> $0
Exch $1 ; Stack: $1 $0
Push $2 ; Stack: $2 $1 $0
; $0 = file
; $1 = string
FileOpen $2 "$0" "a"
FileSeek $2 0 END
FileWrite $2 $1
FileClose $2
Pop $2 ; Stack: $1 $0
Pop $1 ; Stack: $0
Pop $0 ; Stack: -empty-
FunctionEnd

Section Test
${writeFile} "$TEMP\a_log_file.txt" "A log entry"
SectionEnd
</highlight-nsis>

As you can see, this allows you to combine the best of both worlds by reducing code redundancy both in your installation script -and- in the compiled installer and allowing you to 'pass' parameters/arguments to a function by using a macro as an intermediate. And in the end, your code looks even cleaner.

= Caveats - or Pros/Cons =
Now you might think that macros and functions rather look the same - when should you use which? That all depends on your needs / desires for the most part. However, there are certainly pros/cons to both.

As pointed in the definitions already, there are some immediately obvious advantages over each other:
'''Macros'''
* + easier follow (the code simply gets copy/pasted)
* + can easily pass parameters / arguments
* - code gets duplicated in the compiled result
Note that the code duplication is marginal (the files you are installing are typically much larger than the base installer code), and with compression it becomes even less of an issue.

'''Functions'''
* + code does not get duplicated in the compiled result
* - cannot easily pass parameters / arguments
* - a bit less easy to follow
( The Hybrid approach pretty much eliminates the parameter / argument passing con of Functions )

However, there are also some less obvious Pros/Cons.
For example, Macros are faster to execute than Functions, as there are no opcodes for calling / returning required in the installer. However, this is also marginal and even on older hardware negligable.

More intricate Pros/Cons are described in the next sections.

== Macros ==
=== labels ===
As a Macro literally gets inserted, or copy/pasted, into your code when compiling you may find yourself running into an issue of duplicating labels;

Example 3.1.1
<highlight-nsis>
!macro LoopThreeTimes
StrCpy $0 0
loop:
IntOp $0 $0 + 1
IntCmp $0 3 end
goto loop
end:
!macroend

Section Test
IfFileExists "$TEMP\install.log" end
!insertmacro LoopThreeTimes
end:
SectionEnd
</highlight-nsis>

The above could be read as:

Example 3.1.2
<highlight-nsis>
Section Test
IfFileExists "$TEMP\install.log" end
StrCpy $0 0
loop:
IntOp $0 $0 + 1
IntCmp $0 3 end
goto loop
end:
end:
SectionEnd
</highlight-nsis>

And the problem should be clear - there are now two labels named "end", which is not allowed. You could rename your labels in your macros to be supposedly unique - in example 3.1.1 you could call them "LoopThreeTimes_loop" and "LoopThreeTimes_end". But what if you use the macro more than once in the same section?

Example 3.1.3
<highlight-nsis>
Section Test
IfFileExists "$TEMP\install.log" end
StrCpy $0 0
loop:
IntOp $0 $0 + 1
IntCmp $0 3 LoopThreeTimes_end
goto loop
LoopThreeTimes_end:
StrCpy $0 0
loop:
IntOp $0 $0 + 1
IntCmp $0 3 LoopThreeTimes_end
goto loop
LoopThreeTimes_end:
end:
SectionEnd
</highlight-nsis>

You then again get a duplicate label name. A common way to prevent this is to actually make the label names unique for each time the macro is inserted. You can do this by adding a line number that is first defined to the label;

Example 3.1.3
<highlight-nsis>
!macro LoopThreeTimes
!define ID ${__LINE__}
StrCpy $0 0
loop_${ID}:
IntOp $0 $0 + 1
IntCmp $0 3 end_${ID}
goto loop_${ID}
end_${ID}:
!undefine ID
!macroend

Section Test
IfFileExists "$TEMP\install.log" end
!insertmacro LoopThreeTimes
end:
SectionEnd
</highlight-nsis>

Which would then end up as (presuming the line number the !define was on was 55):
Example 3.1.4
<highlight-nsis>
Section Test
IfFileExists "$TEMP\install.log" end
StrCpy $0 0
loop_55:
IntOp $0 $0 + 1
IntCmp $0 3 end_55
goto loop_55
end_55:
end:
SectionEnd
</highlight-nsis>
You can read more about this in: [[Tutorial: Using labels in macro's]]

Although this is a reasonably minor Con, given the easy workaround, it should be clear that Functions do not suffer from any issues with labels at all.

== Functions ==
=== File command ===
When you use a Macro, the code gets inserted or copy/pasted if you will into the area of use. This becomes especially important when you use the File command. Consider the following two examples:

Example 3.2.1 - Macro
<highlight-nsis>
!macro InstallFilesTo Path Filespec
SetOutPath "${Path}"
File "${Filespec}
!macroend

Section Test
!insertmacro InstallFilesTo "$INSTDIR" "data\*.*"
SectionEnd
</highlight-nsis>

Example 3.2.2 - Function
<highlight-nsis>
Function InstallFilesTo
Exch $0
Exch
Exch $1
SetOutPath "$1"
File "$0"
Pop $1
Pop $0
FunctionEnd

Section Test
Push "data\*.*"
Push "$INSTDIR"
Call InstallFilesTo
SectionEnd
</highlight-nsis>

The two perform exactly the same job, namely installing all files in the installer source's "data" sub-folder to the installation folder.

The big difference is that with the Macro variant, the size of the files can directly be added to the Section. Which means that your installer will correct report the amount of free space required on the drive, and the "SectionGetSize" command will work correctly.

With the Function variant, the compiler doesn't know to figure this out, and the required space is not calculated correctly, nor does "SectionGetSize" work correctly.

A workaround for this would be to use "SectionSetSize" where appropriate, but it does mean that you would need to know the size of the files -before- you use "SectionSetSize", which would have to be handled by a separate NSIS script, or some cheating by extracting the file before actually installing, getting the file size, and then moving it or deleting it when installing/not installing. In other words, there is no easy / proper workaround for it.

= Conclusion =
Although Macros and Functions are very similar beasts, each has its strengths and weaknesses, and certainly things to look out for. In general, however, you can follow these guidelines:
* if you're not using the code more than once and it's just a single line or a few lines, don't bother using either a Macro or a Function.
* if you're not using the code more than once, but it's a good number of lines and is really a procedure that you want to easily be able to maintain or is otherwise just clogging up the view of the surrounding code, consider putting it into a Macro.
* if you're using non-trivial code more than once, always consider putting it into a Macro or Function
* if it's a lot of code (many, many lines), considering using a Function rather than a Macro
* if you need to use the File command, consider using a Macro rather than a Function - or, if possible, re-think the process to keep the File command outside of the Function.
* if you don't want to fuss around with labels, consider using a Function rather than a Macro - or consider using the work-around which is really quite painless.
* consider setting up a !define for your Macros to make the code cleaner
* consider using the Hybrid approach whenever you decided to go with a Function but need to pass parameters/arguments

[[Category:Scripting FAQ]]

Macro vs Function

2006-09-16T15:46:52Z

Animaether: Finished for now

{{PageAuthor|Animaether}}
Macros and Functions in NSIS are powerful tools to help make coding your installer easier and more flexible. They can also be very powerful tools, allowing you to extend the NSIS scripting language to an extent - LogicLib is a great example of this.

= Definitions =
== Macros ==
From the NSIS help file: "Macros are used to insert code at compile time, depending on defines and using the values of the defines. The macro's commands are inserted at compile time. This allows you to write a general code only once and use it a lot of times but with a few changes."

If you are new to macros in any scripting language, then this may sound a bit confusing. Let's go through a few examples to show what the above means.

"Macros are used to insert code at compile time"

What this means is that the code you define in a macro will simply be inserted at the location of your !insertmacro, as if copy/pasted, when you compile your installer script.

Example 1.1.1
<highlight-nsis>
!macro Hello
DetailPrint "Hello world"
!macroend

Section Test
!insertmacro Hello
SectionEnd
</highlight-nsis>

Could be seen as just:

Example 1.1.2
<highlight-nsis>
Section Test
DetailPrint "Hello world"
SectionEnd
</highlight-nsis>

The above is obviously just a simple example with a single line and really wouldn't be a good use of macros. But if you have multiple lines of code that you may have to use over and over again, it may be a good idea to start using a macro for it; it allows you to just make the any changes once in the macro, and it will automatically be changed anywhere you insert it. It also just makes your code look a lot cleaner (a single !insertmacro line vs perhaps a dozen lines) which makes it a lot easier to follow and edit.

"depending on defines and using the values of the defines"

That bit is most likely to sound confusing, but gets a little more clear once you read the definition of macros in another section of the NSIS help:

"macro definitions can have one or more parameters defined. The parameters may be accessed the same way a !define would (e.g. ${PARMNAME}) from inside the macro."

If you are familiar with scripting in other languages, this may sound familiar to you, except in the context of functions - but please do not mix this up with Functions as they exist in the NSIS language.. we'll get to those later.

What the above means is that you can have a macro take parameters, or arguments, and use those within the macro:

Example 1.1.3
<highlight-nsis>
!macro Hello What
DetailPrint "Hello ${What}"
!macroend

Section Test
!insertmacro Hello "World"
!insertmacro Hello "Tree"
!insertmacro Hello "Flower"
SectionEnd
</highlight-nsis>

Could be seen as just:

Example 1.1.4
<highlight-nsis>
Section Test
DetailPrint "Hello World"
DetailPrint "Hello Tree"
DetailPrint "Hello Flower"
SectionEnd
</highlight-nsis>

However, you only needed a single macro definition to get these three different results. Let's take a more complex example, straight from the NSIS Help. In NSIS, a Function can only be specified as being for the Installer, or the Uninstaller (prefixed by "un."). The reason for this is that it allows the compiler to make a smaller Uninstaller if it does not need the Installer's functions, and vice-versa. However, sometimes you may have a function that both the Installer and the Uninstaller require. You could then code the Function twice:

Example 1.1.5
<highlight-nsis>
Function SomeFunc
; Lots of code here
FunctionEnd

Function un.SomeFunc
; Lots of code here
FunctionEnd
</highlight-nsis>
However, as it should be apparent, if there's lots of code involved you have two separate areas where you have to make code changes, your code looks less clean, etc.

With the use of macros, this can easily be resolved by writing a macro around the function that simply adds the "un." prefix when requested:

Example 1.1.6
<highlight-nsis>
!macro SomeFunc un
Function ${un}SomeFunc
; lots of code here
FunctionEnd
!macroend
!insertmacro SomeFunc ""
!insertmacro SomeFunc "un."
</highlight-nsis>

The above will then be written out as example 1.1.5, but now you only have a single portion of code to maintain.

For more information on this specific topic, see: [[Sharing_functions_between_Installer_and_Uninstaller]]

== Functions ==
Let's start again with what the NSIS Help file says on them:

"Functions are similar to Sections in that they contain zero or more instructions."

Let's try a different definition. Functions are like macros, except that the code does -not- actually get inserted or copy/pasted, if you will, when compiling. The compiled code only exists just once in your final installer.

A Function use equivalent to the Macro example 1.1.1 would be:

Example 1.2.1
<highlight-nsis>
Function Hello
DetailPrint "Hello world"
FunctionEnd

Section Test
Call Hello
SectionEnd
</highlight-nsis>

You also cannot pass parameters/arguments to Functions as easily as you can with Macros. I.e. the following is NOT a valid code equivalent of Example 1.1.3:

Example: 1.2.2
<highlight-nsis>
Function Hello What
DetailPrint "Hello ${What}"
FunctionEnd

Section Test
Call Hello "World"
Call Hello "Tree"
Call Hello "Flower"
SectionEnd
</highlight-nsis>

You could, of course, try to take a page out of the earlier installer/uninstaller book and wrap the function in a macro:

Example 1.2.3
<highlight-nsis>
!macro Hello What
Function Hello
DetailPrint "Hello ${What}"
FunctionEnd
!macroend

Section Test
!insertmacro Hello "World"
SectionEnd
</highlight-nsis>
But this is -also- invalid code, as the code would end up having a Function definition within a section, which is not allowed:

Example 1.2.4
<highlight-nsis>
Section Test
Function Hello
DetailPrint "Hello ${What}"
FunctionEnd
SectionEnd
</highlight-nsis>

( even if Function definitions were allowed within Sections, keep in mind that you would have more than a single Function named "Hello" - which is also not allowed )

Instead, passing parameters/arguments to Functions is typically done through variables...

Example 1.2.5
<highlight-nsis>
var myVar

Function Hello
DetailPrint "Hello $myVar"
FunctionEnd

Section Test
StrCpy $myVar "World"
Call Hello
SectionEnd
</highlight-nsis>

...or, more commonly, the stack (to save memory used by variables)

Example 1.2.6
<highlight-nsis>
Function Hello
Exch $0
DetailPrint "Hello $0"
Pop $0
FunctionEnd

Section Test
Push "World"
Call Hello
SectionEnd
</highlight-nsis>

Which ends up acting as (but please note that the code is not actually inserted as such!):

Example 1.2.7
<highlight-nsis>
Section Test
Push "World"
; At this point, the stack looks like the following (top is left, bottom is right)
; :: "World" -rest of the stack, if anything-
Exch $0
; At this point the old value of $0 is now at the top of the stack, while "World" is copied into variable $0
; :: old$0 -rest of the stack, if anything-
DetailPrint "Hello World"
Pop $0
; At this point the old value of $0 is restored, and the stack just looks like the following:
; :: -rest of the stack, if anything-
</highlight-nsis>

Functions can either clear the stack relevant to the function, as in the above, or they can leave an item on the stack for use after the function.

Example 1.2.8
<highlight-nsis>
Function isDir
Exch $0
IfFileExists "$0\*.*" _dir _notdir
_dir:
StrCpy $0 "true"
return
_notdir:
StrCpy $0 "false"
FunctionEnd

Section Test
Push "some path on your drive"
Call isDir
Pop $0
SectionEnd
</highlight-nsis>

Where in the above code, after the call to "isDir", $0 contains "true" if the path was a directory, and "false" if not.

= Hybrid =
Mainly because of the fact that you can't easily pass parameters to Functions, many users adopt a hybrid approach employing both macros -and- functions, and a little bit of a define. (a define just allows you to say that e.g. "NSIS" means "Nullsoft Scriptable Install System" without having to write out as much).

Example 2.1
<highlight-nsis>
!define writeFile "!insertmacro writeFile"

!macro writeFile File String
Push ${File}
Push ${String}
Call writeFile
!macroend

Function WriteFile
; Stack: <file> <string>
ClearErrors
Exch $0 ; Stack: $0 <string>
Exch ; Stack: <string> $0
Exch $1 ; Stack: $1 $0
Push $2 ; Stack: $2 $1 $0
; $0 = file
; $1 = string
FileOpen $2 "$0" "a"
FileSeek $2 0 END
FileWrite $2 $1
FileClose $2
Pop $2 ; Stack: $1 $0
Pop $1 ; Stack: $0
Pop $0 ; Stack: -empty-
FunctionEnd

Section Test
${writeFile} "$TEMP\alogfile.txt" "A log entry"
SectionEnd
</highlight-nsis>

As you can see, this allows you to combine the best of both worlds by reducing code redundancy both in your installation script -and- in the compiled installer and allowing you to 'pass' parameters/arguments to a function by using a macro as an intermediate. And in the end, your code looks even cleaner.

= Caveats - or Pros/Cons =
Now you might think that macros and functions rather look the same - when should you use which? That all depends on your needs / desires for the most part. However, there are certainly pros/cons to both.

As pointed in the definitions already, there are some immediately obvious advantages over eachother:
'''Macros'''
* + easier follow (the code simply gets copy/pasted)
* + can easily pass parameters / arguments
* - code gets duplicated in the compiled result
Note that the code duplication is marginal (the files you are installing are typically much larger than the base installer code), and with compression even moreso.

'''Functions'''
* + code does not get duplicated in the compiled result
* - cannot easily pass parameters / arguments
* - a bit less easy to follow
( The Hybrid approach pretty much eliminates the parameter / argument passing con of Functions )

However, there are also some less obvious Pros/Cons.
For example, Macros are faster to execute than Functions, as there are no opcodes for calling / returning required in the installer. However, this is also marginal and even on older hardware neglectable.

More intricate Pros/Cons are described in the next sections.

== Macros ==
=== labels ===
As a Macro literally gets inserted, or copy/pasted, into your code when compiling you may find yourself running into an issue of duplicating labels;

Example 3.1.1
<highlight-nsis>
!macro LoopThreeTimes
StrCpy $0 0
loop:
IntOp $0 $0 + 1
IntCmp $0 3 end
goto loop
end:
!macroend

Section Test
IfFileExists "$TEMP\install.log" end
!insertmacro LoopThreeTimes
end:
SectionEnd
</highlight-nsis>

The above could be read as:

Example 3.1.2
<highlight-nsis>
Section Test
IfFileExists "$TEMP\install.log" end
StrCpy $0 0
loop:
IntOp $0 $0 + 1
IntCmp $0 3 end
goto loop
end:
end:
SectionEnd
</highlight-nsis>

And the problem should be clear - there are now two labels named "end", which is not allowed. You could rename your labels in your macros to be supposedly unique - in example 3.1.1 you could call them "LoopThreeTimes_loop" and "LoopThreeTimes_end". But what if you use the macro more than once in the same section?

Example 3.1.3
<highlight-nsis>
Section Test
IfFileExists "$TEMP\install.log" end
StrCpy $0 0
loop:
IntOp $0 $0 + 1
IntCmp $0 3 LoopThreeTimes_end
goto loop
LoopThreeTimes_end:
StrCpy $0 0
loop:
IntOp $0 $0 + 1
IntCmp $0 3 LoopThreeTimes_end
goto loop
LoopThreeTimes_end:
end:
SectionEnd
</highlight-nsis>

You then again get a duplicate label name. A common way to prevent this is to actually make the label names unique for each time the macro is inserted. You can do this by adding a line number that is first defined to the label;

Example 3.1.3
<highlight-nsis>
!macro LoopThreeTimes
!define ID ${__LINE__}
StrCpy $0 0
loop_${ID}:
IntOp $0 $0 + 1
IntCmp $0 3 end_${ID}
goto loop_${ID}
end_${ID}:
!undefine ID
!macroend

Section Test
IfFileExists "$TEMP\install.log" end
!insertmacro LoopThreeTimes
end:
SectionEnd
</highlight-nsis>

Which would then end up as (presuming the line number the !define was on was 55):
Example 3.1.4
<highlight-nsis>
Section Test
IfFileExists "$TEMP\install.log" end
StrCpy $0 0
loop_55:
IntOp $0 $0 + 1
IntCmp $0 3 end_55
goto loop_55
end_55:
end:
SectionEnd
</highlight-nsis>
You can read more about this in: [[Tutorial: Using labels in macro's]]

Although this is a reasonably minor Con, given the easy workaround, it should be clear that Functions do not suffer from any issues with labels at all.

== Functions ==
=== File command ===
When you use a Macro, the code gets inserted or copy/pasted if you will into the area of use. This becomes especially important when you use the File command. Consider the following two examples:

Example 3.2.1 - Macro
<highlight-nsis>
!macro InstallFilesTo Path Filespec
SetOutPath "${Path}"
File "${Filespec}
!macroend

Section Test
!insertmacro InstallFilesTo "$INSTDIR" "data\*.*"
SectionEnd
</highlight-nsis>

Example 3.2.2 - Function
<highlight-nsis>
Function InstallFilesTo
Exch $0
Exch
Exch $1
SetOutPath "$1"
File "$0"
Pop $1
Pop $0
FunctionEnd

Section Test
Push "data\*.*"
Push "$INSTDIR"
Call InstallFilesTo
SectionEnd
</highlight-nsis>

The two perform exactly the same job, namely installing all files in the installer source's "data" subfolder to the installation folder.

The big difference is that with the Macro variant, the size of the files can directly be added to the Section. Which means that your installer will correct report the amount of free space required on the drive, and the "SectionGetSize" command will work correctly.

With the Function variant, the compiler doesn't know to figure this out, and the required space is not calculated correctly, nor does "SectionGetSize" work correctly.

A workaround for this would be to use "SectionSetSize" where appropriate, but it does mean that you would need to know the size of the files -before- you use "SectionSetSize", which would have to be handled by a separate NSIS script, or some cheating by extracting the file before actually installing, getting the file size, and then moving it or deleting it when installing/not installing. In other words, there is no easy / proper workaround for it.

[[Category:Scripting FAQ]]

Macro vs Function

2006-09-16T14:19:01Z

Animaether:

{{PageAuthor|Animaether}}
''This page is currently in process of heavy editing. Please do not modify!''

Macros and Functions in NSIS are powerful tools to help make coding your installer easier and more flexible. They can also be very powerful tools, allowing you to extend the NSIS scripting language to an extent - LogicLib is a great example of this.

= Definitions =
== Macros ==
From the NSIS help file: "Macros are used to insert code at compile time, depending on defines and using the values of the defines. The macro's commands are inserted at compile time. This allows you to write a general code only once and use it a lot of times but with a few changes."

If you are new to macros in any scripting language, then this may sound a bit confusing. Let's go through a few examples to show what the above means.

"Macros are used to insert code at compile time"

What this means is that the code you define in a macro will simply be inserted at the location of your !insertmacro, as if copy/pasted, when you compile your installer script.

Example 1.1.1
<highlight-nsis>
!macro Hello
DetailPrint "Hello world"
!macroend

Section Test
!insertmacro Hello
SectionEnd
</highlight-nsis>

Could be seen as just:

Example 1.1.2
<highlight-nsis>
Section Test
DetailPrint "Hello world"
SectionEnd
</highlight-nsis>

The above is obviously just a simple example with a single line and really wouldn't be a good use of macros. But if you have multiple lines of code that you may have to use over and over again, it may be a good idea to start using a macro for it; it allows you to just make the any changes once in the macro, and it will automatically be changed anywhere you insert it. It also just makes your code look a lot cleaner (a single !insertmacro line vs perhaps a dozen lines) which makes it a lot easier to follow and edit.

"depending on defines and using the values of the defines"

That bit is most likely to sound confusing, but gets a little more clear once you read the definition of macros in another section of the NSIS help:

"macro definitions can have one or more parameters defined. The parameters may be accessed the same way a !define would (e.g. ${PARMNAME}) from inside the macro."

If you are familiar with scripting in other languages, this may sound familiar to you, except in the context of functions - but please do not mix this up with Functions as they exist in the NSIS language.. we'll get to those later.

What the above means is that you can have a macro take parameters, or arguments, and use those within the macro:

Example 1.1.3
<highlight-nsis>
!macro Hello What
DetailPrint "Hello ${What}"
!macroend

Section Test
!insertmacro Hello "World"
!insertmacro Hello "Tree"
!insertmacro Hello "Flower"
SectionEnd
</highlight-nsis>

Could be seen as just:

Example 1.1.4
<highlight-nsis>
Section Test
DetailPrint "Hello World"
DetailPrint "Hello Tree"
DetailPrint "Hello Flower"
SectionEnd
</highlight-nsis>

However, you only needed a single macro definition to get these three different results. Let's take a more complex example, straight from the NSIS Help. In NSIS, a Function can only be specified as being for the Installer, or the Uninstaller (prefixed by "un."). The reason for this is that it allows the compiler to make a smaller Uninstaller if it does not need the Installer's functions, and vice-versa. However, sometimes you may have a function that both the Installer and the Uninstaller require. You could then code the Function twice:

Example 1.1.5
<highlight-nsis>
Function SomeFunc
; Lots of code here
FunctionEnd

Function un.SomeFunc
; Lots of code here
FunctionEnd
</highlight-nsis>
However, as it should be apparent, if there's lots of code involved you have two separate areas where you have to make code changes, your code looks less clean, etc.

With the use of macros, this can easily be resolved by writing a macro around the function that simply adds the "un." prefix when requested:

Example 1.1.6
<highlight-nsis>
!macro SomeFunc un
Function ${un}SomeFunc
; lots of code here
FunctionEnd
!macroend
!insertmacro SomeFunc ""
!insertmacro SomeFunc "un."
</highlight-nsis>

The above will then be written out as example 1.1.5, but now you only have a single portion of code to maintain.

For more information on this specific topic, see: [[Sharing_functions_between_Installer_and_Uninstaller]]

== Functions ==
Let's start again with what the NSIS Help file says on them:

"Functions are similar to Sections in that they contain zero or more instructions."

Let's try a different definition. Functions are like macros, except that the code does -not- actually get inserted or copy/pasted, if you will, when compiling. The compiled code only exists just once in your final installer.

A Function use equivalent to the Macro example 1.1.1 would be:

Example 1.2.1
<highlight-nsis>
Function Hello
DetailPrint "Hello world"
FunctionEnd

Section Test
Call Hello
SectionEnd
</highlight-nsis>

However, you cannot pass parameters/arguments to Functions as easily as you can with Macros. I.e. the following is NOT a valid code equivalent of Example 1.1.3:

Example: 1.2.2
<highlight-nsis>
Function Hello What
DetailPrint "Hello ${What}"
FunctionEnd

Section Test
Call Hello "World"
Call Hello "Tree"
Call Hello "Flower"
SectionEnd
</highlight-nsis>

You could, of course, try to take a page out of the earlier installer/uninstaller book and wrap the function in a macro:

Example 1.2.3
<highlight-nsis>
!macro Hello What
Function Hello
DetailPrint "Hello ${What}"
FunctionEnd
!macroend

Section Test
!insertmacro Hello "World"
SectionEnd
</highlight-nsis>
But this is -also- invalid code, as the code would end up having a Function definition within a section, which is not allowed:

Example 1.2.4
<highlight-nsis>
Section Test
Function Hello
DetailPrint "Hello ${What}"
FunctionEnd
SectionEnd
</highlight-nsis>

( even if Function definitions were allowed within Sections, keep in mind that you would have more than a single Function named "Hello" - which is also not allowed )

Instead, passing parameters/arguments to Functions is typically done through variables...

Example 1.2.5
<highlight-nsis>
var myVar

Function Hello
DetailPrint "Hello $myVar"
FunctionEnd

Section Test
StrCpy $myVar "World"
Call Hello
SectionEnd
</highlight-nsis>

...or, more commonly, the stack (to save memory used by variables)

Example 1.2.6
<highlight-nsis>
Function Hello
Exch $0
DetailPrint "Hello $0"
Pop $0
FunctionEnd

Section Test
Push "World"
Call Hello
SectionEnd
</highlight-nsis>

Which ends up acting as (but please note that the code is not actually inserted as such!):

Example 1.2.7
<highlight-nsis>
Section Test
Push "World"
; At this point, the stack looks like the following (top is left, bottom is right)
; :: "World" -rest of the stack, if anything-
Exch $0
; At this point the old value of $0 is now at the top of the stack, while "World" is copied into variable $0
; :: old$0 -rest of the stack, if anything-
DetailPrint "Hello World"
Pop $0
; At this point the old value of $0 is restored, and the stack just looks like the following:
; :: -rest of the stack, if anything-
</highlight-nsis>

Functions can either clear the stack relevant to the function, as in the above, or they can leave an item on the stack for use after the function.

Example 1.2.8
<highlight-nsis>
Function isDir
Exch $0
IfFileExists "$0\*.*" _dir _notdir
_dir:
StrCpy $0 "true"
return
_notdir:
StrCpy $0 "false"
FunctionEnd

Section Test
Push "some path on your drive"
Call isDir
Pop $0
SectionEnd
</highlight-nsis>

Where in the above code, after the call to "isDir", $0 contains "true" if the path was a directory, and "false" if not.

= Hybrid =
Mainly because of the fact that you can't easily pass parameters to Functions, many users adopt a hybrid approach employing both macros -and- functions, and a little bit of a define. (a define just allows you to say that e.g. "NSIS" means "Nullsoft Scriptable Install System" without having to write out as much).

Example 2.1
<highlight-nsis>
!define writeFile "!insertmacro writeFile"

!macro writeFile File String
Push ${File}
Push ${String}
Call writeFile
!macroend

Function WriteFile
; Stack: <file> <string>
ClearErrors
Exch $0 ; Stack: $0 <string>
Exch ; Stack: <string> $0
Exch $1 ; Stack: $1 $0
Push $2 ; Stack: $2 $1 $0
; $0 = file
; $1 = string
FileOpen $2 "$0" "a"
FileSeek $2 0 END
FileWrite $2 $1
FileClose $2
Pop $2 ; Stack: $1 $0
Pop $1 ; Stack: $0
Pop $0 ; Stack: -empty-
FunctionEnd

Section Test
${writeFile} "$TEMP\alogfile.txt" "A log entry"
SectionEnd
</highlight-nsis>

As you can see, this allows you to combine the best of both worlds by reducing code redundancy both in your installation script -and- in the compiled installer and allowing you to 'pass' parameters/arguments to a function by using a macro as an intermediate. And in the end, your code looks even cleaner.

= Caveats - or Pros/Cons =
- insert content -

[[Category:Scripting FAQ]]

Macro vs Function

2006-09-16T13:26:44Z

Animaether:

Macro vs Function

2006-09-16T13:15:07Z

Animaether:

Macro vs Function

2006-09-16T13:08:23Z

Animaether:

Macro vs Function

2006-09-16T13:04:05Z

Animaether:

''This page is currently in process of heavy editing. Please do not modify!''

Macros and Functions in NSIS are powerful tools to help make coding your installer easier and more flexible. They can also be very powerful tools, allowing you to extend the NSIS scripting language to an extent - LogicLib is a great example of this.

= Definitions =
== Macros ==
From the NSIS help file: "Macros are used to insert code at compile time, depending on defines and using the values of the defines. The macro's commands are inserted at compile time. This allows you to write a general code only once and use it a lot of times but with a few changes."

If you are new to macros in any scripting language, then this may sound a bit confusing. Let's go through a few examples to show what the above means.

"Macros are used to insert code at compile time"

What this means is that the code you define in a macro will simply be inserted at the location of your !insertmacro, as if copy/pasted, when you compile your installer script.
<highlight-nsis>
!macro Hello
DetailPrint "Hello world"
!macroend

Section Test
!insertmacro Hello
SectionEnd
</highlight-nsis>
Example 1.1

Could be seen as just:
<highlight-nsis>
Section Test
DetailPrint "Hello world"
SectionEnd
</highlight-nsis>
Example 1.2

The above is obviously just a simple example with a single line and really wouldn't be a good use of macros. But if you have multiple lines of code that you may have to use over and over again, it may be a good idea to start using a macro for it; it allows you to just make the any changes once in the macro, and it will automatically be changed anywhere you insert it. It also just makes your code look a lot cleaner (a single !insertmacro line vs perhaps a dozen lines) which makes it a lot easier to follow and edit.

"depending on defines and using the values of the defines"

That bit is most likely to sound confusing, but gets a little more clear once you read the definition of macros in another section of the NSIS help:

"macro definitions can have one or more parameters defined. The parameters may be accessed the same way a !define would (e.g. ${PARMNAME}) from inside the macro."

If you are familiar with scripting in other languages, this may sound familiar to you, except in the context of functions - but please do not mix this up with Functions as they exist in the NSIS language.. we'll get to those later.

What the above means is that you can have a macro take parameters, or arguments, and use those within the macro:

<highlight-nsis>
!macro Hello What
DetailPrint "Hello ${What}"
!macroend

Section Test
!insertmacro Hello "World"
!insertmacro Hello "Tree"
!insertmacro Hello "Flower"
SectionEnd
</highlight-nsis>
Example 2.1

Could be seen as just:
<highlight-nsis>
DetailPrint "Hello World"
DetailPrint "Hello Tree"
DetailPrint "Hello Flower"
</highlight-nsis>
Example 2.2

However, you only needed a single macro definition to get these three different results. Let's take a more complex example, straight from the NSIS Help. In NSIS, a Function can only be specified as being for the Installer, or the Uninstaller (prefixed by "un."). The reason for this is that it allows the compiler to make a smaller Uninstaller if it does not need the Installer's functions, and vice-versa. However, sometimes you may have a function that both the Installer and the Uninstaller require. You could then code the Function twice:
<highlight-nsis>
Function SomeFunc
; Lots of code here
FunctionEnd

Function un.SomeFunc
; Lots of code here
FunctionEnd
</highlight-nsis>
Example 2.3
However, as it should be apparent, if there's lots of code involved you have two separate areas where you have to make code changes, your code looks less clean, etc.

With the use of macros, this can easily be resolved by writing a macro around the function that simply adds the "un." prefix when requested:
<highlight-nsis>
!macro SomeFunc un
Function ${un}SomeFunc
; lots of code here
FunctionEnd
!macroend
!insertmacro SomeFunc ""
!insertmacro SomeFunc "un."
</highlight-nsis>
Example 2.4

The above will then be written out as example 2.3, but now you only have a single portion of code to maintain.

For more information on this specific topic, see: [[Sharing_functions_between_Installer_and_Uninstaller]]

[[Category:Scripting FAQ]]

Macro vs Function

2006-09-16T12:42:44Z

Animaether:

Macro vs Function

2006-09-16T12:28:40Z

Animaether:

Just making sure this page exists - initial content + formatting and linking to from the FAQ will follow.

[[Category:Scripting FAQ]]

Macro vs Function

2006-09-16T12:22:41Z

Animaether: initial creation

Just making sure this page exists - initial content + formatting and linking to from the FAQ will follow.