Macro vs Function: Difference between revisions
Animaether (talk | contribs) No edit summary |
Animaether (talk | contribs) mNo edit summary |
||
Line 1: | Line 1: | ||
{{PageAuthor|Animaether}} | |||
''This page is currently in process of heavy editing. Please do not modify!'' | ''This page is currently in process of heavy editing. Please do not modify!'' | ||
Line 12: | Line 13: | ||
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. | 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. | ||
<small>Example 1.1</small> | |||
<highlight-nsis> | <highlight-nsis> | ||
!macro Hello | !macro Hello | ||
Line 21: | Line 24: | ||
SectionEnd | SectionEnd | ||
</highlight-nsis> | </highlight-nsis> | ||
Could be seen as just: | Could be seen as just: | ||
<small>Example 1.2</small> | |||
<highlight-nsis> | <highlight-nsis> | ||
Section Test | Section Test | ||
Line 29: | Line 32: | ||
SectionEnd | SectionEnd | ||
</highlight-nsis> | </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. | 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. | ||
Line 43: | Line 45: | ||
What the above means is that you can have a macro take parameters, or arguments, and use those within the macro: | What the above means is that you can have a macro take parameters, or arguments, and use those within the macro: | ||
<small>Example 2.1</small> | |||
<highlight-nsis> | <highlight-nsis> | ||
!macro Hello What | !macro Hello What | ||
Line 54: | Line 57: | ||
SectionEnd | SectionEnd | ||
</highlight-nsis> | </highlight-nsis> | ||
Could be seen as just: | Could be seen as just: | ||
<small>Example 2.2</small> | |||
<highlight-nsis> | <highlight-nsis> | ||
DetailPrint "Hello World" | DetailPrint "Hello World" | ||
Line 62: | Line 66: | ||
DetailPrint "Hello Flower" | DetailPrint "Hello Flower" | ||
</highlight-nsis> | </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: | 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: | ||
<small>Example 3.1</small> | |||
<highlight-nsis> | <highlight-nsis> | ||
Function SomeFunc | Function SomeFunc | ||
Line 74: | Line 79: | ||
FunctionEnd | FunctionEnd | ||
</highlight-nsis> | </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. | 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: | 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: | ||
<small>Example 3.2</small> | |||
<highlight-nsis> | <highlight-nsis> | ||
!macro SomeFunc un | !macro SomeFunc un | ||
Line 87: | Line 93: | ||
!insertmacro SomeFunc "un." | !insertmacro SomeFunc "un." | ||
</highlight-nsis> | </highlight-nsis> | ||
The above will then be written out as example | The above will then be written out as example 3.1, 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]] | For more information on this specific topic, see: [[Sharing_functions_between_Installer_and_Uninstaller]] | ||
[[Category:Scripting FAQ]] | [[Category:Scripting FAQ]] |
Revision as of 13:08, 16 September 2006
Author: Animaether (talk, contrib) |
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
!macro Hello DetailPrint "Hello world" !macroend Section Test !insertmacro Hello SectionEnd
Could be seen as just: Example 1.2
Section Test DetailPrint "Hello world" SectionEnd
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 2.1
!macro Hello What DetailPrint "Hello ${What}" !macroend Section Test !insertmacro Hello "World" !insertmacro Hello "Tree" !insertmacro Hello "Flower" SectionEnd
Could be seen as just:
Example 2.2
DetailPrint "Hello World" DetailPrint "Hello Tree" DetailPrint "Hello Flower"
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 3.1
Function SomeFunc ; Lots of code here FunctionEnd Function un.SomeFunc ; Lots of code here FunctionEnd
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 3.2
!macro SomeFunc un Function ${un}SomeFunc ; lots of code here FunctionEnd !macroend !insertmacro SomeFunc "" !insertmacro SomeFunc "un."
The above will then be written out as example 3.1, 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