forked from icculus/mojosetup
-
Notifications
You must be signed in to change notification settings - Fork 0
/
docs.txt
1516 lines (1016 loc) · 58.6 KB
/
docs.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
Using MojoSetup.
If there are gaps in this documentation, please ask on the MojoSetup mailing
list. To subscribe to the list, go here...
https://icculus.org/mailman/listinfo/mojosetup
...and then questions can go to [email protected]. This document will
be updated as we see what parts are confusing, so feedback is appreciated.
Putting together a MojoSetup installer involves five general steps:
1) Compile the software.
2) Set up the installer filesystem structure.
3) Write a config file.
4) Add any localized strings.
5) Package up the final file for distribution.
Each step has a lot of details, but all installers basically follow those same
basic development steps.
Compile the software:
You will need some tools. First, you'll need your platform's favorite build
tools. You'll also need CMake (https://www.cmake.org/), and a Git
(https://git-scm.com/) client. These are all available for most
popular operating systems, and some not-so-popular ones.
Get the latest version of MojoSetup from Git:
git clone https://github.com/icculus/mojosetup.git
Then you'll need to point CMake at it:
cd mojosetup
mkdir cmake-build
cd cmake-build
ccmake ..
Tweak the build settings to your liking. You'll want to set CMAKE_BUILD_TYPE
to MinSizeRel, to make the compiled binary be as small as possible, and
then trim out features you don't need. For example, you can drop the
HTTP and FTP support to save about 25 kilobytes on the binary. You can also
drop support for various archive types, pieces of Lua you don't plan to use,
etc.
CMake will get you project files for whatever development environment you use
(Makefiles, XCode, Visual Studio, etc). Build the project. You should end
up with some shared libraries for whatever GUIs you left enabled, and
a mojsetup binary. Strip the debug symbols and put these aside for later.
If you are building MojoSetup without the Lua parser, you'll want to build
the separate Lua compiler (MOJOSETUP_BUILD_LUAC in ccmake). That will produce
a "mojoluac" binary. Put that aside for later, too.
Set up the installer filesystem structure:
This is fairly easy. The installer eventually wants to see a directory
tree like this:
data/
scripts/
guis/
meta/
This is called the "Base Archive," even if it's a real directory tree in the
physical filesystem and not in an actual archive, such as a .zip file.
"data" is where the installer looks for files included in the installer itself
that need installation (as opposed to those being read from the network
or a CD-ROM, etc). READMEs and EULAs go in here, too. The installer
doesn't care how things under data/ are arranged.
"guis" is where the installer looks for those shared libraries that got
built in the first step. Copy them in here, if you built any.
"meta" contains installer metadata: graphics for splash screens, etc. It's sort
of a catch-all for things that don't fit elsewhere.
"scripts" is where Lua scripts go. You'll put your config file in here
(config.lua), the translation table (localizations.lua), and whatever other
scripts come with MojoSetup, which are required application logic. The
installer will not work if you don't include all these files! This
directory can hold either .lua files (source code), or their .luac
equivalents. If you built MojoSetup without the Lua parser to save space,
you'll need to compile the .lua sources into .luac objects now, or the
installer won't know what to do with them. It's safe to compile them even
if you include the parser.
cd scripts
../mojoluac -o config.luac config.lua
cd ..
You can strip debug symbols from the compiled scripts to save more space,
but you'll get less useful information if there's a script error:
cd scripts
../mojoluac -s -o config.luac config.lua
cd ..
Once you finish constructing this directory tree, put it aside for later.
Write a config file:
This is the complicated part, and where most of your effort will be spent.
This document will try to cover all the provided facilities, but as the
configuration file also provides a robust programming language, not only
is the full scope beyond this document, you can also accomplish all sorts
of things we haven't even considered yet.
Configuration files are Lua scripts. The Lua language and runtime library is
documented at https://www.lua.org/, and they sell an excellent book called
"Programming in Lua" which is a fast read and will demonstrate all manners
of wild and interesting features of the language. That being said, most
people rolling config files don't need any significant Lua expertise, and
basic config files don't need any programming experience at all.
MojoSetup provides some functions for your benefit, if you want to add any
programming logic to your config. These are documented below.
The config file is named config.lua, and it must be a text file in UTF-8
encoding. If you are doing any programming, you may use any symbol you like,
so long as the name isn't "Setup", "MojoSetup", or any of the standard Lua
runtime names like "string" or "table".
Configuration files are a hierarchy of elements that take this form:
Setup.DataType
{
someattribute = value1,
someotherattribute = value2,
}
Elements can nest:
Setup.DataType
{
someattribute = value1,
someotherattribute = value2,
Setup.AnotherDataType
{
something = value3,
}
}
Case is important! Setup.Option and Setup.option are NOT the same thing!
Here are the elements, and the attributes they can possess.
There are some specifiers by the attributes:
mustExist: Error if is nil (usually if you don't specify it). The other
"mustBe" descriptions consider nil to be valid when mustExist
isn't explicitly mentioned.
no default: This attribute will not have a default if not specified.
default X: This attribute defaults to X if not specified.
mustBeString: Error if isn't a string.
cantBeEmpty: Error is this string is "". String can be nil, though.
mustBeBool: Error if isn't true, false, or nil.
mustBeFunction: Error if isn't a function (can be C or Lua).
mustBeNumber: Error if isn't a number.
mustBeUrl: Error if isn't a string that matches the regexp "^.+://.-/.*".
mustBePerms: Error if isn't a valid permissions string for the platform.
mustBeStringOrTableOfStrings: Error if isn't a string or an array of strings.
mustBeSplashPosition: Error if isn't a string in the set of "top",
"left", "bottom", "right", or "background".
Attributes that aren't explicitly specified take on their default value. In
cases without a default, they are effectively set to Lua's "nil" value.
This makes boolean values be treated as "false." Plan accordingly.
Setup.Package:
All configurations need at least one Setup.Package element. Every other
element is added under Setup.Package. One full run of the installer is
done for each Setup.Package. You can have multiple packages in one file, and
the installer will run through for each one as if the program was started
multiple times. If there are multiple packages and an installation failure
occurs, all successfully-installed packages will remain. In most cases, you
only want one Setup.Package and should use Setup.Option to cull pieces
of the package.
Setup.Package attributes:
vendor (no default, mustExist, mustBeString, cantBeEmpty)
This is a unique identifier for your organization. This should be in the
format "companyname.dom" ... the hope is that your primary website is
a unique identifier for your company. If your website is www.icculus.org,
you'd enter your vendor setting as "icculus.org" ... just the hostname and
top-level domain. This is used largely by the OS to maintain packages
(Mac OS X application bundles, vendor IDs for Unix desktop menus, etc).
This is, in theory, never shown to the user, so you don't need this to
actually exist as a website with meaningful content, so long as you can
reasonably assure that the string is unique and follows the "host.dom"
format.
id (no default, mustExist, mustBeString, cantBeEmpty)
This is a unique identifier for your package. Currently it is used as
the base of the install path, but future features may use it for other
things. Set this to something short, unique, and human-readable, like
"mygame".
disabled (no default, mustBeBool)
If this is true, the entire package will be skipped by the installer. You
probably want this to be true, but you might need to programmatically shut
off a whole package.
description (no default, mustExist, mustBeString, cantBeEmpty)
This is your product's name. This will be displayed in the title bar, and
other locations during installation.
version (no default, mustExist, mustBeString, cantBeEmpty)
This is the version of this package. This is arbitrary, and doesn't matter
to the installer what you specify. It's usually a value like "1.0" or
"beta3"
The installer may use this for future features, like upgrading previous
installations.
destination (no default, mustBeString, cantBeEmpty)
This attribute can be used to force the installation into a specific
location in the physical filesystem. Unless you are building something
very specific (like device drivers for a well-defined platform), you
probably should not use this attribute. If destination isn't forced,
the installer will prompt the user, possibly recommending locations
to him.
dataprefix (default: "data/", mustBeString)
This attribute can be used to force the installer to pull data files
from a location other than data/. The use of the default data/
is strongly recommended; use this option only with great care.
recommended_destinations (no default, mustBeStringOrTableOfStrings)
This attribute lets you define some favorable places to install the
package. You can have a table of strings or a single string:
recommended_destinations = MojoSetup.info.homedir,
...or...
recommended_destinations = { "/usr/local/games", "/opt/games" },
These strings are presented in the UI to the user when selecting an
install destination, but they can override them with their own choice.
The "id" attribute is appended to these before displaying to the end
user, so they'll see, for example, "/usr/local/games/mygame" and
"/opt/games/mygame" ... if a listed directory is determined to be
unwritable to the user (lack of permissions), it will be removed from the
list before presentation to the user.
recommended_full_destinations (no default, mustBeStringOrTableOfStrings)
This attribute lets you define some favorable places to install the
package. You can have a table of strings or a single string:
recommended_full_destinations = MojoSetup.info.homedir .. "/mygame",
...or...
recommended_full_destinations = { "/usr/local/games/mygame",
"/opt/games/mygame" },
These strings are presented in the UI to the user when selecting an
install destination, but they can override them with their own choice.
Unlike for the recommended_destinations attribute, the "id" attribute
is not appended to these. If a listed directory is determined to be
unwritable to the user (lack of permissions), it will be removed from the
list before presentation to the user.
precheck (no default, mustBeFunction)
If this attribute is defined, it is called by the installer after the
configuration is parsed and the GUI has started, but before the user has
interacted with the installer at all. It passes the finalized
Setup.Package table as a parameter.
checkdst (no default, mustBeFunction)
If this attribute is defined, it is called by the installer to validate
the user provided install path. It gets the finalized Setup.Package table
and the just entered destination path as parameters. If it returns nil
the destination path is accepted. Otherwise an error message must be
returned. If it is not empty it will be displayed in a message box before
giving the user a chance to change the install path.
preflight (no default, mustBeFunction)
If this attribute is defined, it is called by the installer after the
user has chosen options to install. The heavy-lifting of the installer
is about to begin: downloading files and installing the Package. It
passes the finalized Setup.Package table as a parameter.
preinstall (no default, mustBeFunction)
If this attribute is defined, it is called by the installer after all
needed external files are downloaded and installation of files is about
to begin. It passes the finalized Setup.Package table as a parameter.
postinstall (no default, mustBeFunction)
If this attribute is defined, it is called by the installer after the
entire package was successfully installed to disk. It passes the finalized
Setup.Package table as a parameter.
preuninstall (no default, mustBeFunction)
If this attribute is defined, it is called by the uninstaller after the
user confirms that uninstallation is acceptable and deletion of
files is about to begin. It passes something like the finalized
Setup.Package table as a parameter. This function is serialized for later
use, in a different program running in a different context: it may NOT use
any Lua upvalues (they will be local variables set to nil when the function
runs) and any globals you reference may or may not exist when the
function runs. Try to do the bare minimum here if you must use this hook.
postuninstall (no default, mustBeFunction)
If this attribute is defined, it is called by the uninstaller after the
uninstallation has successfully finished. It passes something like the
finalized Setup.Package table as a parameter. This function is serialized
for later use, in a different program running in a different context: it
may NOT use any Lua upvalues (they will be local variables set to nil when
the function runs) and any globals you reference may or may not exist when
the function runs. Try to do the bare minimum here if you must use this
hook.
postexec (no default, mustBeString)
This attribute can be used to chain the installer to another process
on a successful installation. The string can contain $DESTINATION which
will be replaced with the installation destination.
delete_error_is_fatal (default true, mustBeBool)
If we cannot exactly delete every file during uninstallation, we will
terminate at the very first failure if this is true. Otherwise, we
will delete every file we can.
updateurl (no default, mustBeUrl)
This is written to the manifest files for the aid of external tools, but
isn't currently used by MojoSetup itself.
splash (no default, mustBeString, cantBeEmpty)
This is the filename of an image file that will be used in the GUI.
The file should be placed in the "meta" directory (but you should omit
"meta" from this string). Please note that not all GUIs can show graphics,
and you must build MojoSetup with support for whatever image format you
used for the file.
splashpos (no default, mustBeSplashPosition)
This is the location of the splash image that will be used in the GUI.
Please note that not all GUIs can show graphics, or handle the position
requested, but this makes a best effort. If you specify a splash and no
position, the GUI is free to place it wherever it thinks is best.
url (no default, mustBeString, cantBeEmpty)
(!!! FIXME) This attribute is for future expansion.
once (default true, mustBeBool)
(!!! FIXME) This attribute is for future expansion.
category (default "Games", mustBeString, cantBeEmpty)
(!!! FIXME) This attribute is for future expansion.
promptoverwrite (default true, mustBeBool)
(!!! FIXME) This attribute is for future expansion.
Please refer to Setup.File.allowoverwrite for now.
binarypath (no default, mustBeString, cantBeEmpty)
(!!! FIXME) This attribute is for future expansion.
superuser (default false, mustBeBool)
(!!! FIXME) This attribute is for future expansion.
write_manifest (default true, mustBeBool)
If true, MojoSetup will create a hidden metadata directory in the
destination folder with lists of all files installed and some other
pertinent facts about the installed package. This allows other tools to
operate on the installation later, such as a software updater program or
an uninstaller. MojoSetup will also install tools in the metadata
directory to aid in manifest management and uninstallation.
Unless your package is a well-defined, static installation, you probably
want this. It adds a couple hundred kilobytes to the final install in the
filesystem (but not your download package), and puts an extra directory
in there (Usually called ".mojosetup", and hidden from the end-user).
support_uninstall (default true, mustBeBool)
If true, MojoSetup will include a means for the end-user to uninstall
this package. On Unix, this takes the form of a shell script in the
destination folder, on Windows, this hooks your package into the
"Add/Remove Programs" control panel.
If you enable support_uninstall, you must enable write_manifest, or the
installer will refuse to run to alert you to the problem immediately.
Please note that if you haven't anything outside the destination folder
to clean up, uninstall is merely a user-friendly formality; MojoSetup
doesn't implicitly write anything to the system outside this folder, so
the user can just drag it to the trash in the basic usage scenario. Indeed,
on Mac OS X, this is Apple's recommended "uninstall" procedure. On Windows,
hooking into Add/Remove Programs is probably desirable in all cases.
Enabling this option adds very little overhead to the normal install, once
you swallow the cost from write_manifest.
Setup.Eula:
This element can be a child of Setup.Package or Setup.Option. It can be
used to display a license agreement to the end user, which they must agree
to before installation can proceed. If they refuse the license, the installer
terminates without installing anything (or, in the Setup.Option case, steps
back in the installation to let them change options, so they can disable the
installation of whatever they disagree with). There can be multiple
Setup.Eula elements listed, in which case the end user will be asked to
agree to each license individually before installation may proceed. The
Setup.Package licenses are shown first before any other interaction occurs,
and the Setup.Option licenses are shown after the user selects her install
options.
Setup.Eula attributes:
description (no default, mustExist, mustBeString, cantBeEmpty)
This is a brief description of the license, used for title bars and such.
source (no default, mustExist, mustBeString, cantBeEmpty)
This is a filename in the Base Archive's "data" directory that contains
the license text. Currently this must be a text file in UTF-8 encoding.
accept_not_needed (false, mustBeBool)
If true, then the user does not have to explicitly accept the EULA.
Setup.Readme:
This element is a child of Setup.Package. It can be used to display a
information about the package to the end user, such as a welcome message,
FAQs, or other orientation information. There can be multiple Setup.Readme
elements listed, in which case the end user will be shown each readme
individually before installation may proceed. The readmes are shown after
any EULA elements in the Setup.Package. EULA elements in a Setup.Option
are shown later, however.
Setup.Readme attributes:
description (no default, mustExist, mustBeString, cantBeEmpty)
This is a brief description of the Readme, used for title bars and such.
source (no default, mustExist, mustBeString, cantBeEmpty)
This is a filename in the Base Archive's "data" directory that contains
the readme text. Currently this must be a text file in UTF-8 encoding.
Setup.ProductKey:
This element can be a child of Setup.Package or Setup.Option. It can be
used to prompt the user for a "CD key" or some other sort of code that
is required to install the product. If they can't enter a valid key,
the installer terminates without installing anything (or, in the
Setup.Option case, steps back in the installation to let them change options,
so they can disable the installation of whatever they don't have keys for).
There can be multiple Setup.ProductKey elements listed, in which case the
end user will be asked to enter each key individually before installation
may proceed. The Setup.Package keys are requested after any global EULAs are
agreed to, and the Setup.Option keys are requested after any per-option
EULAs.
Setup.ProductKey attributes:
description (no default, mustExist, mustBeString, cantBeEmpty)
This is a brief description of the key being requested, used for
title bars and such.
format (no default, mustBeString, cantBeEmpty)
This specifies the exact format a key must be. This is a string of
characters. The GUI will not allow the user to continue until they either
enter a string that matches this format or abort entry.
The following characters are acceptable in a format string:
'X', '#', ' ', '-', '?', '*'
'X' means "any letter."
'#' means "any number."
'?' means "any letter or number."
'*' means "any character."
' ' and '-' specify new blocks of text.
Obviously, these are not regular expressions, or filename-style wildcards.
For example, if you expect a valid product key to be four segments of
four numbers, followed by two letters, your format would be this:
####-####-####-#### XX
'-' and ' ' are optional. The GUI may be able to optimize for these cases,
such as splitting input into separate text boxes. Users won't have to
enter these characters; MojoSetup will fill them in if they are missing.
If no format is specified, the user may enter any string.
verify (no default, nil, mustBeFunction)
This function is called after the user finishes typing in their key. It
allows the installer to verify that the key is valid before continuing.
The function returns true or false, and maybe optionally return a second
value that transforms the key, perhaps to encrypt it before writing it
to disk.
Here is a very basic example function in Lua:
local function verify_cdkey(key)
if key == "this-is-a-valid-cdkey" then
-- You could just "return true" too, to not change the key.
return true, key .. "-some-extra-junk-on-the-end"
end
return false
end
One could also call into a C function, which can be handy to reuse the
same key validation routines that your installed application would use.
MojoSetup's license allows for you to statically link such code without
releasing the source code to it. To do so, please see the function
luahook_verifyproductkey() in lua_glue.c, and change it to fit your needs.
If no verify function is specified, no verification occurs; MojoSetup
assumes that whatever the user entered is okay, only making sure it
matched the specified format.
In the case of a successful verification, MojoSetup will quietly continue
on. If you wish to say something to the user here, such as: "don't tell
anyone your CD key, we will never ask you for it," then you should call
MojoSetup.msgbox() before returning from your verify function (or, in C
code: GGui->msgbox("window title", "message to show").
destination (no default, nil, mustBeString, cantBeEmpty)
This is where MojoSetup should write the product key. It will be a text
file with the final ASCII key string.
If no destination is specified, the product key is not written to disk.
This may be desirable if the installer just needs to make sure a key is
available and valid.
On Windows, the destination is allowed to use a magic format for targeting
a specific key in the Windows Registry instead of a file, such as:
"$WINDOWSREGISTRY/HKEY_LOCAL_MACHINE/Software/MyApp/ProductKey"
Setup.Media:
This element is required if you need to install data from removable media,
such as a DVD-ROM drive. The installer needs a means to identify the
media as the correct source when it is connected to the system.
Setup.Media attributes:
id (no default, mustExist, mustBeString, cantBeEmpty)
A unique specifier for this media, such as "disc1" or "game-disc". This
will be used for Setup.File.source: "media://game-disc/path/filename.zip"
description (no default, mustExist, mustBeString, cantBeEmpty)
A human-readable description of this media, such as "MyGame Disc 2". This
string will be used when the end user must be prompted to insert a new
piece of media to continue the installation.
uniquefile (no default, mustExist, mustBeString, cantBeEmpty)
This is a path that is unique to this media, relative to its root
directory, such as "sounds/guitar.wav". The installer looks at all
media available to the system until it finds this path exists, to
determine if the correct media has been made available by the end user.
Setup.Option:
This element defines an optional section of the install, and is a child
of Setup.Package. You must have at least one Setup.Option in your
configuration, but you can make it mandatory with the "required" attribute
if you don't want it to be actually optional.
The GUI will show all selectable options to the end user, and they can
pick and choose the parts they want. If there are no optional portions of
the install, the GUI will skip the option selection screen.
Setup.Options can nest. If a parent option is unchecked in the GUI, its
child options become disabled and will be considered unchecked also when
installation proceeds.
Setup.Option
{
description = "Wing Commander 1"
source = "base:///wc1.zip",
-- This option can only install if "Wing Commander 1" is checked too.
Setup.Option
{
description = "WC1 Speech Pack",
source = "base:///wc1sp.zip",
},
},
Setup.Option attributes:
disabled (default false, mustBeBool)
If true, this whole group (including all children) will be removed from
the GUI, and the installer will treat all the child options as unchecked.
If an option has both "required" and "disabled" set to true, then
"disabled" takes precedence.
value (default false, mustBeBool)
If true, the checkbox will be checked by default in the GUI. Checked
options are installed.
required (default false, mustBeBool)
If true, the option won't be shown to the end user, but will just be
treated as if it was checked when installation proceeds. If an option
has both "required" and "disabled" set to true, then "disabled" takes
precedence.
bytes (no default, mustExist, mustBeNumber)
This is the size, in bytes, of files this option will write to disk. The
installer uses this to determine space requirements for the total install.
If you don't know the size, you should set this to -1, but this will
disable some functionality.
description (no default, mustExist, mustBeString, cantBeEmpty)
This string will be shown to the end user, as a label with the GUI's
checkbox.
tooltip (no default, mustBeString, cantBeEmpty)
This string will be used in mouseover "tooltips" in GUI environments for
this option's UI widget. There is no guarantee that they will be shown to
a user in any GUI target, so don't rely on them!
Setup.OptionGroup:
This element can be the parent or child of Setup.Option, or a child of
Setup.Package. It contains of a collection of Setup.Option elements.
The children Setup.Options will be grouped radio buttons in the GUI instead
of individual checkboxes. As such, only one child Setup.Option in an
Setup.OptionGroup will be checked in the GUI.
Setup.OptionGroup
{
description = "Language",
Setup.Option { description = "English", source = "base:///en.zip" },
Setup.Option { description = "French", source = "base:///fr.zip" },
Setup.Option { description = "German", source = "base:///fr.zip" },
},
Setup.OptionGroup attributes:
disabled (no default, mustBeBool)
If true, this option (including all children) will be removed from
the GUI, and the installer will treat this and all child options as
unchecked.
description (no default, mustExist, mustBeString, cantBeEmpty)
This string will be shown to the end user, as a label with the GUI's
radio button group.
tooltip (no default, mustBeString, cantBeEmpty)
This string will be used in mouseover "tooltips" in GUI environments for
this option's UI widget. There is no guarantee that they will be shown to
a user in any GUI target, so don't rely on them!
Setup.File:
This element specifies a fileset, a collection of files, to install. These
are children of Setup.Option, and you can specify as many as you like per
option. Each Setup.File represents an "archive," that is, some set of files,
such as a .zip file or a directory.
Setup.File attributes:
source (no default, mustBeUrl)
This is a URL that provides the source for this fileset. You can only
specify archives (directories and files like .zip, .tar, etc), not
specific individual files. If you need a specific file, use its parent
directory here and a "wildcards" attribute.
There are some standard and non-standard URL handlers you can specify:
base:///path/file.ext
This references an archive in the Base Archive, where the "data"
directory is the root...so the above looks for data/path/file.ext in
the Base Archive.
This can install from an archive inside an archive, like this:
base:///mydir/outside.zip/internalpath/inside.tar
media://id/path/file.ext
This references a file on an external media with a specific id,
as defined in a Setup.Media element. The user will be prompted for
the correct media if the installer can't find it. This can install
archives-in-archives, like the base:/// version can.
ftp://hostname.dom/path/file.ext
http://hostname.dom/path/file.ext
The references a file on an FTP or web server. These files will all be
downloaded before local files are installed. You may only specify
archives at this time, not individual files or directories.
MojoSetup must be built with support for the proper network protocol.
destination (no default, mustBeString, cantBeEmpty)
This attribute lets you, across the board, redirect files in this archive
to a specific destination. This is a path relative to the base of the
installation destination path. If the user specified an installation
destination of "/games/mygame", this attribute is "gamemod", and the
source produces a file "maps/level1.map", then the final file written to
disk would be "/games/mygame/gamemod/maps/level1.map".
After the path is prepared with this attribute, it is tested against the
"wildcards" attribute, and if it passes there, it is pushed through the
"filter" attribute.
wildcards (no default, mustBeStringOrTableOfStrings)
This is the first step to culling files from an archive or directory.
Files are only installed if they match a specified wildcard.
Wildcards are simple to use: they only allow '?' for single character
matches and '*' to match a sequence of characters. You may specify a
single string, or a list of wildcards, like this:
-- matches sounds/heroes/laser13.wav and sounds/villians/laser02.wav
wildcards = "sounds/*/laser??.wav"
...or...
-- everything in the maps, sounds, and graphics directories.
-- (this includes subdirs! '*' matches past '/' separators!)
wildcards = { "maps/*", "sounds/*", "graphics/*" }
filter (no default, mustBeFunction)
This is a function that takes two arguments, a string that represents the
path of a single file relative to the root of the installation destination
and a table with additional information about the file.
The table has the following fields:
type (string)
The type of the file.
Valid types are "file", "dir", "symlink" and "unknown".
filesize (number)
The size of the file in bytes.
linkdest (string)
The destination of the symbolic link if the file is of type "symlink" otherwise it's nil.
filename (string)
The file name.
This function may return nil to choose not to install this file, which is
useful for culling files from an archive, or a string that represents a
new destination for the file, which is useful for renaming some files
on-the-fly:
filter = function(dest, ent)
if string.match(dest, ".exe$") then
return nil -- skip Windows .exe files on Unix.
end
if dest == "SOMEFILE.TXT" then
return "somefile.txt" -- force this to lowercase.
end
if ent.type == "dir" then
return dest, "0755" -- make sure directories are created with the proper permission
end
return dest -- everything else can go through as-is.
end
Filters can optionally return a second argument, a string, that defines
the destination file's permissions. This can be omitted, or nil, to use
the default permissions:
filter = function(dest)
if dest == "mygame-binary" then
return dest, "0755" -- make sure it's executable.
end
return dest -- everything else just goes through as-is.
end
Please see the documentation for Setup.File's "permissions" attribute for
further discussion.
allowoverwrite (no default, mustBeBool)
If true, the installer will overwrite existing files without warning. If
false, the user will be prompted before overwriting each file.
Files are actually moved out of the way instead of overwritten, so the
installer can restore them if the install is cancelled or fails mid-way.
They are deleted only after a successful install.
permissions (no default, mustBePerms)
Override the permissions with which the files will be created. This is
a string, not a number...this allows both for future expansion (non-Unix
systems, extended attributes, etc), and works around the fact that Lua
does not have syntax for specifying octal numbers directly.
Currently this string maps to Unix permissions as an octal number:
"0644" would be read/write access for the user, and read-only for the
group and everyone else.
If set to nil or not specified, the new file's permissions will be
whatever is already associated with the file (such as the Unix permissions
in a .tar file's entry).
Please note that files coming from a real filesystem will have their
defaults overridden by MojoSetup (to "0644"), since many operating systems
tend to report every file on a CD-ROM as read-only and executable, which
is frequently not what you want in the installed copy. Plan accordingly.
You can return a permissions string as the second value from your filter
function as well, which may be more efficient if you only need to change
a few files, (each Setup.File has to iterate the whole archive, so you
want to avoid specifying multiple Setup.Files for one archive when
possible), or need to adjust permissions in only a portion of a downloaded
archive. This attribute applies permissions to every file installed
through this element. If this attribute is set and the filter returns a
non-nil permission, the filter takes precedence.
Setup.DesktopMenuItem:
This element specifies a menu item that will be installed in the system
desktop menu: this might be the "Applications" dropdown in the GNOME panel,
or the "Start" bar on Windows, for example. This can be a child of
Setup.Option (in which case it is only considered for installation if the
option itself is too), or Setup.Package (in which case it is always
considered for installation). Some of this element's properties are ignored
on some operating systems, but they are still required both for
cross-platform safety and future expansion.
Setup.DesktopMenuItem attributes:
disabled (no default, mustBeBool)
If this is true, the menu item will be skipped by the installer. You
probably want this to be true, but you might need to programmatically shut
off specific menu items.
name (no default, mustExist, mustBeString, cantBeEmpty)
This is the proper name of the item to be installed ("Firefox").
genericname (no default, mustExist, mustBeString, cantBeEmpty)
This is a generic name for the item to be installed ("Web Browser").
tooltip (no default, mustExist, mustBeString, cantBeEmpty)
This is used as a tooltip for the item by the OS when the user hovers
the mouse pointer over it.
builtin_icon (no default, mustBeBool)
If this is true, then "icon" refers to a platform-dependent standard
icon. Currently, this only makes sense on Unix systems that follow
the freedesktop.org standards. If this is false, then "icon" refers
to a file, relative to the installation's destination directory, which
the must be installed through a Setup.File. Most installers should set
this to false (the default) unless they know what they are doing.
icon (no default, mustExist, mustBeString, cantBeEmpty)
The icon to use with this menu item. Please see builtin_icon for info
on what this string means. The format of files that may be used as icons
varies from platform to platform; you may need to install a different
file programmatically, based on the value of MojoSetup.info.platform.
commandline (no default, mustExist, mustBeString, cantBeEmpty)
This is the command line that will be used to launch the application
when the end user clicks on the desktop menu item. The string "%0" is
replaced with the install destination, so if you need an absolute path
to mygame.exe, and the user is installing to /home/user/mygame, you should
specify "%0/mygame.exe" to get "/home/user/mygame/mygame.exe".
workingdir (no default, mustBeString, cantBeEmpty)
This is the path that should be set to the current working directory when
launching the installed application. The string "%0" is replaced with the
install destination, so if you need an absolute path to somedir, and the
user is installing to /home/user/mygame, you should specify "%0/somedir"
to get "/home/user/mygame/somedir". If not specified, the system will
choose a directory for you, which is not what you want if you need a
specific path. Non-absolute paths are not recommended unless you know what
you're doing.
category (no default, mustExist, mustBeStringOrTableOfStrings)
This is a category (or array of categories) that the menu item applies