dragonleo/NSIS
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

fixed typos in tutorial, forgot to add 2 files

Browse source 
git-svn-id: https://svn.code.sf.net/p/nsis/code/NSIS/trunk@2280 212acab6-be3b-0410-9dea-997c60f758d6
This commit is contained in:
flizebogen 2003-03-11 18:15:03 +00:00
parent 788f9eb974
commit 72a48c4afc
1 changed files with 83 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

83
Docs/src/tutorial.but Normal file
View file

@ -0,0 +1,83 @@
\A{tutorial} Tutorial
\H{tutintro} Introduction
If you download or buy software, most of the time it has been packed with an installer. The programer of the installer copies or updates the files, sets the registry keys, writes the configuration etc. The user goes through a kind of wizard, makes the appropriate choices and waits until the installer finishes.
This way all things have been setup to start the program. The user hasn't to worry about something he maybe forgot because everything necessary was done by the installer.
NSIS is a tool for developers to create such an installer. You can make both basic installers and installers that handles lots of advanced tasks, ask for specific input from the user etc. NSIS is very flexible and its scripting language isn't hard to learn.
NSIS compiles all files and scripts into one executable file, so your application will be easy to distribute. NSIS is also the smallest installer system available, with an overhead of only 30-50 KB.
\H{tutscriptfiles} Script Files
To create a NSIS installer you have to write a NSIS script.
A NSIS Script is nothing more than a simple text file.
You can edit it with every text editor you like but I suggest you should use an editor more advanced than notepad. The editor of your choice should be able to show line numbers (The NSIS compiler always shows on which line the error has occurred) and syntax highlighting for better coding. Either you find syntax highlighting files for the editor of your choice on their appropriate homepage or on the \W{http://nsis.sf.net/archive/}{NSIS archive}.
In a NSIS script every line is treated as a command. If your command is too long for one line you can use the \\ at the end of the line. This way the compiler treats the new line as an addition to the previous line and don't expects a new command.
\c Messagebox MB_OK|MB_ICONINFORMATION \
\c "This is a sample that shows how to use line breaks for larger commands in NSIS scripts"
If you want to use characters like " in a string, escape them using $\\“
The default extension for a script is .nsi. But there is also .nsh. An .nsh file is something like a header file in C. You can put functions or macros’s in header files and include the header files in multiple installers. It also makes your scripts better to read.
\H{tutstructure} Scripting structure
A NSIS script contains of 3 parts. These parts are called compiler commands, installer attributes and sections/functions.
\S1{compilercommands} Compiler Commands
Compiler commands will be executed on compile time. They allow you to include header files, execute applications etc. If you want to use constants such as the version of your program it is not necessary to use a run-time variable because the version information will not change during installation.
!define VERSION "1.0.3" is a good example for using the define command. $\{VERSION\} will be replaced by 1.0.3 everywhere in the script.
You can also use macros on compile time. You can use macro’s to insert code on compile time, depending on defines and using the values of the defines. An example of a macro is UpgradeDLL (See \k{upgradedll}), which you can use to upgrade a DLL file. The macro inserts all the commands on compile time, because you need compile time commands such as GetDLLVersion.
\S1{installerattributes} Installer Attributes
Installer Attributes determines the look and the basic behavior of your installation. With these attributes you define what pages are shown in which order, which UI resource should be used, how many installation types exists etc. All of these commands can only be set and are not changeable during runtime.
\S1{sectionsfunctions} Sections/Functions
In a common installer there are several things the user can install. For example the NSIS distribution where you can install the core files, the source files etc. Each of these components is separated in a section.
Of course you can build your installer with only one section, but if you want to use the component page and let the user choose what to install you have to use more than one section. In sections you can execute any kind of command like extracting files, read or write registry keys, INI values etc. You can also use variables and use commands such as StrCmp to check for conditions, just like a real programming language. The complete list of commands can be found here (See \k{instr}).
In functions you can also use any kind of command. There are two kinds of functions. Callback functions and user functions. A callback function will be called by NSIS when a certain event occurs (See \k{callbacks}). Let's say you want to call a specific command if the installer quits with errors than you have to define the callback function .onInstFailed. Callback can be used optional. There is no need to use all of them but to can use them for custom pages, error handling etc.
The other kinds of functions are called user functions. In the user function you can also put any kind of command but the difference is that you have to call the user function yourself. User functions are very useful if you have a set of commands that needs to be executed on several positions in the installer. This way you only need to code them once. To execute a user function use the command "Call" (See \k{call}). The function will be called and after executing the last command of the function the installer executes the next command after your call.
\H{tutcompiler} Compiler
To create an installer you have to compile your script with the makensis compiler.
MakeNSISW is a user interface for the compiler. You can start MakeNSISW and open your script or, if you have installed the shell extensions, you can right-click your .nsi file and select "Compile NSI".
The compiler will check for errors is your script and give you warnings or an error. If an errors occurs (i.e. 2 parameters required but only 1 given) the compiler aborts and a short error message including the line number is printed out. If you have used a command that sets a label such as "Dirtext" more than once the compiler only gives a warning.
The built of the installer is entirely made in memory. That means that every file, icons and other resources are combined in memory and than written to the file. If you are building large installers, the compile process can take a few minutes.
NSIS supports different compression methods: ZLib und Bzip2. ZLib is useful for small installers. BZip2 gives better results for large installers, but requires a bit more memory and is a little slower.
\H{tutenhancing} Enhancing NSIS
NSIS can be extended with plug-ins. Plug-ins are DLL files written in C, C++ or another language that will automatically be extracted to a temporary folder. You can call plug-in functions in your script using the dllname::funtionname command. Perhaps you have noticed the list of plug-ins that is shown at the beginning of the compile process. You can find the plug-ins in the \W{../Plugins/}{Plugins directory}.
There are several plug-ins available, but you can also write your own. InstallOptions is a popular plug-in that you can use to add custom pages to your installers. The Startmenu plug-in provides a page that allows the user to choose a Start Menu folder. There are a lot of plug-ins for different purposes. The help files and samples for the plug-ins can be found in the \W{../Contrib/}{contrib directory}. You can find addition plug-ins at the on-line \W{http://nsis.sf.net/archive/}{NSIS Archive}.
You can also customize the dialog resources without modifying or recompiling the source code. Use a resource editor to customize one of the \W{../contrib/UIs/}{UI files} and use the ChangeUI command to use the customized resources.
A popular user interface for NSIS is the Modern User Interface, with an interface like the wizards of recent Windows versions. The Modern UI is not only a customized resource file, it has a lots of new interface elements. It features a white header to describe the current step, a description area on the component page, a Finish page that allows you to run the application or reboot the system and more. The Modern UI language files make it easy to create a multilingual installer, because they contain translations for every label in the installer.
The Modern UI has a macro system that inserts the code to handle all the new UI elements, so you only have to insert a few lines of code to use it. For more information, check the \W{../Contrib/modern ui/readme.html}{Modern UI Readme} and the Modern UI \W{../examples/modern ui/}{examples}.