https://wiki.amigaos.net/w/api.php?action=feedcontributions&user=Philippe+Ferrucci&feedformat=atom AmigaOS Documentation Wiki - User contributions [en] 2024-03-28T16:40:20Z User contributions MediaWiki 1.34.0 https://wiki.amigaos.net/w/index.php?title=Advanced_Serial_Debugging_Guide&diff=7851 Advanced Serial Debugging Guide 2015-01-26T15:24:38Z <p>Philippe Ferrucci: /* Getting the Most out of Serial Debugging */</p> <hr /> <div>= Author =<br /> <br /> Roman Kargin and Lyle Hazelwood&lt;br/&gt;<br /> Copyright © 2013 Roman Kargin and Lyle Hazelwood&lt;br/&gt;<br /> Proofreading and grammar corrections by the AmigaOS Wiki team.&lt;br/&gt;<br /> <br /> = Introduction =<br /> <br /> While AmigaOS has &quot;hi-level&quot; capabilities to help debug problems (e.g. redirecting debug outputs to memory and displaying the log with DumpDebugBuffer or using serial redirection tools like Sashimi) it is sometimes still not enough. For example, there is no protection for areas like input and Intuition so we can get into a situation where the GUI is not operational but the OS is still working. Intuition, input and any other necessary components can crash and then the GrimReaper utility has no way to spawn itself. Meanwhile, the kernel can still can output debug information about the crash on serial.<br /> <br /> To begin with, you should know that AmigaOS has 2 ''reapers''. One is a user friendly utility from SYS:System called GrimReaper. The GrimReaper can be called a &quot;hi-level&quot; one. Another ''reaper'' is called Reaper which is a part of the kernel itself. The kernel's Reaper actually launches the user-friendly GrimReaper when a required. So, you can imagine that when things get nasty, the kernel's reaper can catch some information and output it to the serial and the OS may die soon after that. Visually, you just see a &quot;freeze&quot; of the OS and you don't know what happened and of course no stack trace or register dump.<br /> <br /> That means that when you want to do some serious work and you need any way to catch your bugs and/or debug any of your problematic code, then serial debugging is the best and only one way. Of course it's still possible to hope that the system friendly GrimReaper will popup for you and that there will be nothing so hardcore which it will crash Intuition and &quot;freeze&quot; the OS but that's just not enough when it come to doing real work.<br /> <br /> You may ask now why the serial port is used at all? Why not parallel or something else? Why does everyone keep telling you to use serial debugging as if there is nothing else you can connect a cable to? The answer is in simplicity and reliability. Serial was chosen because it is simple to transfer data, bit by bit, not like for example done with a parallel port. There are different interfaces which also can transfer information bit by bit (like Ethernet, Firewire and USB) but the standard serial port is common to all platforms and far less complex. It comes as no surprise that the old AmigaOS 3 which works on classic Amigas, all output debug information via serial ports. Now, we have different kinds of hardware where USB is pervasive but USB is more complex and still not as reliable for debugging purposes.<br /> <br /> = Serial and Null Modem =<br /> <br /> == Serial ==<br /> <br /> Serial ports (often called RS-232 but it's really RS-232C) have disappeared as a standard option on many user level computers and have been replaced by USB. You can still find many business level x86 motherboards with serial ports. There are solutions for PC hardware without a serial port like USB to serial converters but we will talk about that later. Right now, all we need to know is that all our PowerPC based Amigas, classic Amigas and even the AmigaOne-X1000 have a serial port and the AmigaOS kernel's reaper outputs debug information over that serial port.<br /> <br /> Serial ports most often come in two pin outs: 9 pins and 25 pins.<br /> <br /> [[File:02-serial_db9.png|frame|center|9 Pin Connector]]<br /> <br /> [[File:01-serial_db25.png|frame|center|25 Pin Connector]]<br /> <br /> The 25 pin one, which is usually called DB25, was the first one and is used on the classic Amigas. After some time, software was simplified to use only half of the pins and then 9 pin connector (usually called DB9 but in reality it is DE9) was created. While classic Amigas have the older serial connectors with 25 pins, the Pegasos2, X1000 and Sams all have 9 pin connectors. In general, it makes no differences for our purposes. This is just information in case you decide to build your cable from scratch.<br /> <br /> While the information given there is enough for our article, you still can check out Wikipedia for more information about serial ports and the RS232C standard itself at http://en.wikipedia.org/wiki/Serial_port.<br /> <br /> == Null Modem ==<br /> <br /> In the good old days, when Modems/Teletypes were used to connect over the serial port, it was expected that one side is the ''Data Terminal Equipment'' (DTE) (usually a computer/terminal) and the other side is ''Data Circuit-terminating Equipment'' (DCE) (usually a modem). One side which is an output on a DTE is an input on a DCE and vice versa. Because of that DCE can be connected to a DTE with a straight wired cable. <br /> <br /> Today things are different. Terminals and modems have mostly disappeared and computers have the same kind of serial port that terminals used to have: DTE. As a result, we can't connect them with a straight, pin to pin cable because it will connect the data transfer pins (TX to TX and RX to RX) like it was when we connect a serial port with a modem and that will not work. The solution is to swap the data transfer wires: TX to RX. That's what is simply called a ''Null Modem Cable'' (though without ground connected which is always better to do).<br /> <br /> Usually when you go into a shop and find a modem cable it is most often not a null modem cable. You need to ask for a null modem cable where the data pins have been crossed over. Visually, the cables look exactly the same. Only the wires inside are not cross over and thus it will not transfer any serial debug output.<br /> <br /> A null modem cable can one of 4 types:<br /> <br /> #No hardware handshaking&lt;br/&gt;This cable has only the data and signal ground wires connected. I.e. RX, TX and ground.<br /> #Loop back handshaking&lt;br/&gt;Just some &quot;cheat&quot; cable to create fake hardware flow control. <br /> #Partial handshaking&lt;br/&gt;Advanced &quot;cheat&quot; cable.<br /> #Full handshaking&lt;br/&gt;No cheats, just everything that can be in null modem cable.<br /> <br /> In general, to create a basic null modem cable (that one, with &quot;no hardware handshaking&quot;) it is enough to cross over pins 2 and 3 (RxD with TxD) and connect the ground pin. Even with such a simple null modem cable of just 3 wires, you will be able to output debug information and everything will work. You can of course build a cable with full handshaking and it will also work but the hardware may or may support it. For example, the X1000 does not support hardware handshaking and even if you have such a cable, the terminal software where you will capture your debug output you still need to choose the &quot;no handshaking&quot; option. Classic Amiga serial ports support hardware h handshaking. For example, AmigaExplorer from AmigaForever transfers data between Amiga and Windows computers via serial and handshaking helps in that case. So it's better to have a full-handshaking cable and to test it with your hardware. But if you need a null modem cable just for capturing debug output, a simple 3 wire null modem cable will allow up to 115200 and it's more than enough.<br /> <br /> {{Note|text=If you have 2 computers which you want to connect via serial ports you need a null modem cable and '''not''' a ''straight'' serial cable.}}<br /> <br /> Since serial ports can be only of 2 types (DB25 and DB9) there are 3 possible pin outs for null modem cables with full handshaking: DB25 to DB25, DB9 to DB9 and DB9 to DB25.<br /> <br /> [[File:03-db25-db25.png|center|800px]]<br /> [[File:05-db9-db9.png|center|800px]]<br /> [[File:04-db25-db9.png|center|800px]]<br /> <br /> DB9 to DB9 serial cables are fairly easy to find in stores today but they are not likely to be null modem cables and you will need to work on them. DB25 are more rare and you may need to build a cable yourself. Just buy connectors and connect the necessary wires as shown above.<br /> <br /> You can also build a cable which has 2 connectors on either side (i.e. DB9 and DB25 on one side and DB9 and DB25 on the other) so you can use either connector type as needed. This can be handy when you have a classic Amiga and modern PowerPC hardware and connected to a PC for example. To build such a cable just follow the same pin logic as shown below and just double them where needed.<br /> <br /> Another way to solve the problem would be to buy a straight serial cable and add a small connector-adapter which will change the wiring from straight to null modem like in the screenshot below:<br /> <br /> [[File:06-null_modem_adapter.png|frame|center]]<br /> <br /> You can find even more information about null modem cables on [http://en.wikipedia.org/wiki/Null_modem Wikipedia].<br /> <br /> = Connect them now! =<br /> <br /> == Serial&lt;-&gt;Serial ==<br /> <br /> There is nothing else you need except a working null modem cable. It must be a real null modem cable or a ''straight'' serial cable with a null modem adapter; doesn't matter which one.<br /> <br /> == Serial&lt;-&gt;USB ==<br /> <br /> This section is important and interesting for anyone who works with AmigaOS. The reason is that it is more difficult to find x86 hardware (which most of us have use as a necessary part of life) with built-in serial ports. It is even more difficult to find a notebook with a serial port. The solution is to use commonly available USB to serial adapters. There are plenty of them from all sorts of different companies. Despite the fact that they are common, some adapters can be better than others. Although most will work without problems and in practice all of the tested ones works fine, you still may found some adapters which can give you some problems. The reason is that USB does not directly translate to serial and data must be buffered between the two while at the same time keeping accurate timing. There is software inside the adapters and more than one way to implement the necessary hardware buffering thus not all adapters are equal and some are better than others. For serious serial work, nothing beats an actual UART which is why they are still an available option on industrial, laboratory and business PCs.<br /> <br /> If you in interested in building a Serial to USB adapter yourself, you can find plans on the Internet. One example is this [http://pinouts.ru/Converters/usb_serial_adapter_pinout.shtml USB to serial adapter].<br /> <br /> [[File:07-usb2serial.png|frame|center]]<br /> <br /> The look of the adapter can be different of course since it depends on what connectors are used when building a cable. I use one from Gembird based on the PS2303 chip on my notebook with Windows XP, where after installing of drivers it shows ups as COM17:<br /> <br /> [[File:08-settings_win_show.png|frame|center]]<br /> <br /> After you have the USB to serial adapter connected in your system, everything will be the same as if you connected Serial with Serial. A null modem cable is still required or a &quot;straight&quot; cable with a null modem adapter.<br /> <br /> == Serial&lt;-&gt;Anything ==<br /> <br /> You can connect serial to any port in a computer. You just need the correct adapter and cable. There are serial to USB (either purchased or made yourself), serial to Firewire adapters, serial to Ethernet, etc.<br /> <br /> What I am trying to point here is that it does not matter how but you still need to make a real serial port in your system. USB to serial adapters are most popular because they are readily available, easy to find, inexpensive and well tested.<br /> <br /> = Terminal Software and port settings =<br /> <br /> Now, after you have your cable connected between 2 machines, you need software which will catch the data from one side. The &quot;receiver&quot; side can be an x86 system with Windows, Linux, Mac OS or whatever else. You could also use an Amiga with AmigaOS, pOS, Unix or whatever else runs on classic Amiga hardware or any kind of another hardware. The software is called &quot;Terminal&quot; software and since many of us use x86 systems to capture debug output from our Amigas, we will start with x86.<br /> <br /> One of the best terminal software packages for x86 is PuTTY. You can get PuTTY from http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html. Be sure that you get latest/full version because there are some stripped versions around with no support of serial connections. The normal version of PuTTY with working serial support will looks like this:<br /> <br /> [[File:09-putty_serial.png|frame|center]]<br /> <br /> On Amiga (if you connect 2 Amigas by serial) you can use the old 68k Term 4.8:<br /> <br /> [[File:10-term48_serial.png|frame|center]]<br /> <br /> On Linux you can also use PuTTY or the well-known minicom.<br /> <br /> Whatever software is used, it is all about getting the debug data from your Amiga. Debug output is ASCII text data, so anything which can just grab information from your serial port and redirect it where you need it (console or file) will work. You can even write your own simple code which will receive data without the need for any terminal programs. But that's in theory, in practice it is better to use something which is already done.<br /> <br /> The settings which you need to use and which always works on any Amiga hardware from which you want to get your serial output are:<br /> <br /> baud: 115200 <br /> data bits: 8 <br /> stop bits: 1 <br /> parity: none <br /> flow control: none<br /> <br /> It may work with other settings (like different parity and flow control), but as it was pointed out before, on some hardware it may not work at all, on another it will not work as intended, so just these setting to do your first test. After all, you can always change your settings later and experiment after everything works.<br /> <br /> = How to redirect debug output to serial =<br /> <br /> By default, AmigaOS debug output is sent to a memory debug buffer and not to serial. This is done for simplicity. If something happens, especially bugs, then just type &quot;DumpDebugBuffer&quot; in a shell and it shows you what the debug output was. This is similar to using the Sashimi tool which redirects serial output to the console.<br /> <br /> For developers, it is usually best to output everything to the serial port so you need to switch the output to serial. There are 2 ways to do this: boot option in the firmware (U-Boot for Sams/Eyetech AmigaOnes, OpenFirmware for Pegasos2 and CFE for X1000) and the &quot;KDebug&quot; utility.<br /> <br /> == Firmware method ==<br /> <br /> Given there are so many different hardware platforms on which to run AmigaOS today, it should come as no surprise that they use different boot firmwares. AmigaOne-XE/MicroA1-C/Sam uses U-Boot, Pegasos2 uses OpenFirmware and the AmigaOne X1000 uses CFE. For all of them the boot menu options can be a bit different and you need to refer to the documentation which comes with the hardware. But in all cases you have a common variable called '''os4_commandline''' which you need to set. The name of that variable is the same for all the hardware platforms which support AmigaOS. Just the way the variable is setup varies.<br /> <br /> For example on Pegasos2 OpenFirmware, to redirect output to serial with the &quot;munge&quot; debug kernel option and debug level 7 in OF you do:<br /> <br /> Pegasos BIOS Extensions Copyright 2001-2004 by bplan GmbH.<br /> All rights Reserved.<br /> Auto-boot in 1 seconds - press ESC to abort, ENTER to boot: aborted<br /> ok#<br /> ok# setenv os4_commandline serial munge debuglevel=7<br /> <br /> and then boot AmigaOS.<br /> <br /> On AmigaOne X1000/CFE set munge, debuglevel to 4 and output to serial:<br /> <br /> setenv -p os4_commandline=&quot;serial munge debuglevel=4&quot;<br /> <br /> and then boot AmigaOS. For CFE if you are not using -p, then the variable is only saved for that session, not permanently.<br /> <br /> On Sam/AmigaOne U-Boot with the same munge, debuglevel=7 and serial redirect:<br /> <br /> setenv os4_commandline &quot;serial munge debuglevel=7&quot;<br /> saveenv<br /> <br /> In other words, use SetEnv to set the os4_commandline variable and then boot the OS. You can also verify what the variable is using the &quot;printenv&quot; command.<br /> <br /> Just so you are not confused, &quot;amigaboot.of&quot; (the code which first boots) is the component which parses the os4_commandline '''firmware variable''' and ''didn't'' parse any command line arguments. It only parses firmware variables and then passes them on to the kernel. If you try something like ''amigaboot.of os4_commandline = &quot;serial&quot;'', it will not work and will be ignored, the same as any other extra parameters you provide. So be sure that you use &quot;setenv&quot; and check via &quot;printenv&quot; that you set the variable correctly.<br /> <br /> == KDebug method ==<br /> <br /> KDebug is command line utility found in SYS:C which communicates with the AmigaOS kernel. With this utility you can redirect your output to serial or memory. It will override whatever you do with the os4_commandline firmware variable. This is very handy for setting different debug levels at the time you need it. For example, you may also put a command in S:User-Startup<br /> run &gt;NIL: kdebug &quot;debug level 5&quot;<br /> run &gt;NIL: kdebug &quot;console serial&quot;<br /> <br /> This will set the debug level to 5 and output via the serial port.<br /> <br /> {{Note|Quotation marks are mandatory when using the KDebug tool. What KDebug does is send whatever string you enter directly to the AmigaOS kernel for interpretation. The KDebug command itself does not parse the string.}}<br /> <br /> {{Note|KDebug method have higher priority. I.e. if you set your environment variable to some values, and then after os is boots use KDebug to change the settings, then they ''will'' be taken in account and previous one will be forgotten. The only thing that you can't enable/disable by KDebug is 'munge'.}}<br /> <br /> = Getting the Most out of Serial Debugging =<br /> <br /> To start with, you need to read the following articles:<br /> # [[Debug_Kernel|The Debug Kernel]]<br /> # [[Exec_Debug|Exec Debug]]<br /> <br /> To get the most out of serial debugging, developers should use what is called the debug kernel (named '''kernel.debug'''). The debug kernel provides you with more functionality compared with the release kernel at the cost of some execution speed. One thing provided is the ability to play with debug levels where you can choose how much &quot;system&quot; debug output you want to see. It's pretty easy to miss the fact that debug levels only work on debug kernels. You can play with levels, see no change, and you then wonder &quot;Why doesn't it work?&quot;. It works, it is just that the kernel should be the debug one.<br /> <br /> And while the debug kernel does give you some debug functionality, it still may not cover everything. For example, tools like the old MungWall tool can do a bit more: debug kernel has only the &quot;munge&quot; feature but not the &quot;wall&quot; feature. Another example is MemGuard (which can be found on [http://www.os4depot.net OS4Depot]) adds additional debug capabilities on top of what the debug kernel provides and catches more difficult to find bugs.<br /> <br /> So, to get most of serial debugging, you need to use a combination: debug kernel with &quot;munge&quot; option enabled, MemGuard running in the background and set debug level to the value you find most informative. Usually 5 or 7 is enough but sometimes, when a bug is behaving very strangely, you can raise the value in the hope that you see something interesting.<br /> <br /> = If nothing works =<br /> <br /> Now on to troubleshooting. If you build/buy a cable, adapters and all the stuff, connect everything, fire up the terminal software, set up everything correctly and still nothing works, then:<br /> <br /> # Check the cable<br /> # Check the ports.<br /> # Check the cable again :)<br /> # Check program's settings and settings of the port if it USB to serial one. <br /> <br /> Be sure that for you have right settings and in the terminal software (especially the baud, flow control and parity).<br /> <br /> If you have a few '''spare''' connectors that you can use for troubleshooting, just solder a jumper between TX and RX (pins 2 and 3 on DB9). <br /> Then open a terminal program on the computer, set it up as described above, and turn &quot;Local Echo&quot; OFF. When Local Echo is OFF it does<br /> NOT show what you are typing, it only shows what comes in over the serial port.<br /> <br /> The &quot;loopback&quot; connector has TX and RX connected, so it will loop whatever you send back to you. Plug a female loopback directly into the serial port connector and you should see whatever you type, because it is being &quot;looped back&quot; through your test plug. Now take the loopback off, connect your cable, and attach a male loopback at the other end of the cable. If you can see your typing, then you are successfully going out the serial port, down your cable, then looping back up the cable and back into your port.. You get the idea. Having one male and one female &quot;loopback&quot; will let you test ALMOST every possible cable, connection, and software configuration.<br /> <br /> Desperate times: If you don't have any &quot;spare&quot; connectors or a soldering iron, a small paper clip can be used instead of a male loopback connector.. Just bend the clip and insert the ends into pins 2 and 3 of the cable end, and connect the other end to the serial port being tested. If the clip does not fit into the cable end, don't force it, find a smaller paper clip.<br /> <br /> The one thing that a loopback can NOT test is whether your cable is a &quot;Null Modem&quot; cable or not.<br /> The best way to check a cable is with a multimeter. Set it so that when you touch wires on different sides you will heard a &quot;beep&quot; if it connected. That setting usually looks like a little speaker. Check that all of the connections are as they should be. If you use null modem adapter on top of &quot;straight&quot; serial cable, then check it anyway, just in case, with the same meter. The meter lead probably won't fit inside the female connector pins. Another small paper clip helps with that.<br /> <br /> To work properly, (describe a null modem cable, assuming 9 pin to 9 pin):<br /> * Pin 2 on end A should connect to pin 3 on end B.<br /> * Pin 3 on end A should connect to pin 2 on end B.<br /> * Pin 5 on end A should connect to pin 5 on end B.<br /> <br /> If these three connections work, it should be enough to get you going.<br /> <br /> = Final words =<br /> <br /> While this topic is more or less an easy one, there wasn't a guide, until now, which describes everything from the beginning. What kind of cable you can use, how to build it, how to use USB to serial adapters, what settings should be used and what to do with it all. We hope that this guide will at least cover all the gaps and any developers told to &quot;use serial debugging&quot; will just read that article and will have no questions. Anyway, if you have any more info to add, or just found a wrong part somewhere, just send an email to kas1e@yandex.ru or use the [http://www.amigaos.net/Contact AmigaOS Contact Form] and we can update article.<br /> <br /> = Links =<br /> <br /> [1.] http://en.wikipedia.org/wiki/Serial_port<br /> [2.] http://en.wikipedia.org/wiki/Null_modem<br /> [3.] [[Debug_Kernel|Debug Kernel]]<br /> [4.] [[Exec_Debug|Exec Debug]]</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=Advanced_Serial_Debugging_Guide&diff=7850 Advanced Serial Debugging Guide 2015-01-26T15:22:22Z <p>Philippe Ferrucci: /* Getting the Most out of Serial Debugging */</p> <hr /> <div>= Author =<br /> <br /> Roman Kargin and Lyle Hazelwood&lt;br/&gt;<br /> Copyright © 2013 Roman Kargin and Lyle Hazelwood&lt;br/&gt;<br /> Proofreading and grammar corrections by the AmigaOS Wiki team.&lt;br/&gt;<br /> <br /> = Introduction =<br /> <br /> While AmigaOS has &quot;hi-level&quot; capabilities to help debug problems (e.g. redirecting debug outputs to memory and displaying the log with DumpDebugBuffer or using serial redirection tools like Sashimi) it is sometimes still not enough. For example, there is no protection for areas like input and Intuition so we can get into a situation where the GUI is not operational but the OS is still working. Intuition, input and any other necessary components can crash and then the GrimReaper utility has no way to spawn itself. Meanwhile, the kernel can still can output debug information about the crash on serial.<br /> <br /> To begin with, you should know that AmigaOS has 2 ''reapers''. One is a user friendly utility from SYS:System called GrimReaper. The GrimReaper can be called a &quot;hi-level&quot; one. Another ''reaper'' is called Reaper which is a part of the kernel itself. The kernel's Reaper actually launches the user-friendly GrimReaper when a required. So, you can imagine that when things get nasty, the kernel's reaper can catch some information and output it to the serial and the OS may die soon after that. Visually, you just see a &quot;freeze&quot; of the OS and you don't know what happened and of course no stack trace or register dump.<br /> <br /> That means that when you want to do some serious work and you need any way to catch your bugs and/or debug any of your problematic code, then serial debugging is the best and only one way. Of course it's still possible to hope that the system friendly GrimReaper will popup for you and that there will be nothing so hardcore which it will crash Intuition and &quot;freeze&quot; the OS but that's just not enough when it come to doing real work.<br /> <br /> You may ask now why the serial port is used at all? Why not parallel or something else? Why does everyone keep telling you to use serial debugging as if there is nothing else you can connect a cable to? The answer is in simplicity and reliability. Serial was chosen because it is simple to transfer data, bit by bit, not like for example done with a parallel port. There are different interfaces which also can transfer information bit by bit (like Ethernet, Firewire and USB) but the standard serial port is common to all platforms and far less complex. It comes as no surprise that the old AmigaOS 3 which works on classic Amigas, all output debug information via serial ports. Now, we have different kinds of hardware where USB is pervasive but USB is more complex and still not as reliable for debugging purposes.<br /> <br /> = Serial and Null Modem =<br /> <br /> == Serial ==<br /> <br /> Serial ports (often called RS-232 but it's really RS-232C) have disappeared as a standard option on many user level computers and have been replaced by USB. You can still find many business level x86 motherboards with serial ports. There are solutions for PC hardware without a serial port like USB to serial converters but we will talk about that later. Right now, all we need to know is that all our PowerPC based Amigas, classic Amigas and even the AmigaOne-X1000 have a serial port and the AmigaOS kernel's reaper outputs debug information over that serial port.<br /> <br /> Serial ports most often come in two pin outs: 9 pins and 25 pins.<br /> <br /> [[File:02-serial_db9.png|frame|center|9 Pin Connector]]<br /> <br /> [[File:01-serial_db25.png|frame|center|25 Pin Connector]]<br /> <br /> The 25 pin one, which is usually called DB25, was the first one and is used on the classic Amigas. After some time, software was simplified to use only half of the pins and then 9 pin connector (usually called DB9 but in reality it is DE9) was created. While classic Amigas have the older serial connectors with 25 pins, the Pegasos2, X1000 and Sams all have 9 pin connectors. In general, it makes no differences for our purposes. This is just information in case you decide to build your cable from scratch.<br /> <br /> While the information given there is enough for our article, you still can check out Wikipedia for more information about serial ports and the RS232C standard itself at http://en.wikipedia.org/wiki/Serial_port.<br /> <br /> == Null Modem ==<br /> <br /> In the good old days, when Modems/Teletypes were used to connect over the serial port, it was expected that one side is the ''Data Terminal Equipment'' (DTE) (usually a computer/terminal) and the other side is ''Data Circuit-terminating Equipment'' (DCE) (usually a modem). One side which is an output on a DTE is an input on a DCE and vice versa. Because of that DCE can be connected to a DTE with a straight wired cable. <br /> <br /> Today things are different. Terminals and modems have mostly disappeared and computers have the same kind of serial port that terminals used to have: DTE. As a result, we can't connect them with a straight, pin to pin cable because it will connect the data transfer pins (TX to TX and RX to RX) like it was when we connect a serial port with a modem and that will not work. The solution is to swap the data transfer wires: TX to RX. That's what is simply called a ''Null Modem Cable'' (though without ground connected which is always better to do).<br /> <br /> Usually when you go into a shop and find a modem cable it is most often not a null modem cable. You need to ask for a null modem cable where the data pins have been crossed over. Visually, the cables look exactly the same. Only the wires inside are not cross over and thus it will not transfer any serial debug output.<br /> <br /> A null modem cable can one of 4 types:<br /> <br /> #No hardware handshaking&lt;br/&gt;This cable has only the data and signal ground wires connected. I.e. RX, TX and ground.<br /> #Loop back handshaking&lt;br/&gt;Just some &quot;cheat&quot; cable to create fake hardware flow control. <br /> #Partial handshaking&lt;br/&gt;Advanced &quot;cheat&quot; cable.<br /> #Full handshaking&lt;br/&gt;No cheats, just everything that can be in null modem cable.<br /> <br /> In general, to create a basic null modem cable (that one, with &quot;no hardware handshaking&quot;) it is enough to cross over pins 2 and 3 (RxD with TxD) and connect the ground pin. Even with such a simple null modem cable of just 3 wires, you will be able to output debug information and everything will work. You can of course build a cable with full handshaking and it will also work but the hardware may or may support it. For example, the X1000 does not support hardware handshaking and even if you have such a cable, the terminal software where you will capture your debug output you still need to choose the &quot;no handshaking&quot; option. Classic Amiga serial ports support hardware h handshaking. For example, AmigaExplorer from AmigaForever transfers data between Amiga and Windows computers via serial and handshaking helps in that case. So it's better to have a full-handshaking cable and to test it with your hardware. But if you need a null modem cable just for capturing debug output, a simple 3 wire null modem cable will allow up to 115200 and it's more than enough.<br /> <br /> {{Note|text=If you have 2 computers which you want to connect via serial ports you need a null modem cable and '''not''' a ''straight'' serial cable.}}<br /> <br /> Since serial ports can be only of 2 types (DB25 and DB9) there are 3 possible pin outs for null modem cables with full handshaking: DB25 to DB25, DB9 to DB9 and DB9 to DB25.<br /> <br /> [[File:03-db25-db25.png|center|800px]]<br /> [[File:05-db9-db9.png|center|800px]]<br /> [[File:04-db25-db9.png|center|800px]]<br /> <br /> DB9 to DB9 serial cables are fairly easy to find in stores today but they are not likely to be null modem cables and you will need to work on them. DB25 are more rare and you may need to build a cable yourself. Just buy connectors and connect the necessary wires as shown above.<br /> <br /> You can also build a cable which has 2 connectors on either side (i.e. DB9 and DB25 on one side and DB9 and DB25 on the other) so you can use either connector type as needed. This can be handy when you have a classic Amiga and modern PowerPC hardware and connected to a PC for example. To build such a cable just follow the same pin logic as shown below and just double them where needed.<br /> <br /> Another way to solve the problem would be to buy a straight serial cable and add a small connector-adapter which will change the wiring from straight to null modem like in the screenshot below:<br /> <br /> [[File:06-null_modem_adapter.png|frame|center]]<br /> <br /> You can find even more information about null modem cables on [http://en.wikipedia.org/wiki/Null_modem Wikipedia].<br /> <br /> = Connect them now! =<br /> <br /> == Serial&lt;-&gt;Serial ==<br /> <br /> There is nothing else you need except a working null modem cable. It must be a real null modem cable or a ''straight'' serial cable with a null modem adapter; doesn't matter which one.<br /> <br /> == Serial&lt;-&gt;USB ==<br /> <br /> This section is important and interesting for anyone who works with AmigaOS. The reason is that it is more difficult to find x86 hardware (which most of us have use as a necessary part of life) with built-in serial ports. It is even more difficult to find a notebook with a serial port. The solution is to use commonly available USB to serial adapters. There are plenty of them from all sorts of different companies. Despite the fact that they are common, some adapters can be better than others. Although most will work without problems and in practice all of the tested ones works fine, you still may found some adapters which can give you some problems. The reason is that USB does not directly translate to serial and data must be buffered between the two while at the same time keeping accurate timing. There is software inside the adapters and more than one way to implement the necessary hardware buffering thus not all adapters are equal and some are better than others. For serious serial work, nothing beats an actual UART which is why they are still an available option on industrial, laboratory and business PCs.<br /> <br /> If you in interested in building a Serial to USB adapter yourself, you can find plans on the Internet. One example is this [http://pinouts.ru/Converters/usb_serial_adapter_pinout.shtml USB to serial adapter].<br /> <br /> [[File:07-usb2serial.png|frame|center]]<br /> <br /> The look of the adapter can be different of course since it depends on what connectors are used when building a cable. I use one from Gembird based on the PS2303 chip on my notebook with Windows XP, where after installing of drivers it shows ups as COM17:<br /> <br /> [[File:08-settings_win_show.png|frame|center]]<br /> <br /> After you have the USB to serial adapter connected in your system, everything will be the same as if you connected Serial with Serial. A null modem cable is still required or a &quot;straight&quot; cable with a null modem adapter.<br /> <br /> == Serial&lt;-&gt;Anything ==<br /> <br /> You can connect serial to any port in a computer. You just need the correct adapter and cable. There are serial to USB (either purchased or made yourself), serial to Firewire adapters, serial to Ethernet, etc.<br /> <br /> What I am trying to point here is that it does not matter how but you still need to make a real serial port in your system. USB to serial adapters are most popular because they are readily available, easy to find, inexpensive and well tested.<br /> <br /> = Terminal Software and port settings =<br /> <br /> Now, after you have your cable connected between 2 machines, you need software which will catch the data from one side. The &quot;receiver&quot; side can be an x86 system with Windows, Linux, Mac OS or whatever else. You could also use an Amiga with AmigaOS, pOS, Unix or whatever else runs on classic Amiga hardware or any kind of another hardware. The software is called &quot;Terminal&quot; software and since many of us use x86 systems to capture debug output from our Amigas, we will start with x86.<br /> <br /> One of the best terminal software packages for x86 is PuTTY. You can get PuTTY from http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html. Be sure that you get latest/full version because there are some stripped versions around with no support of serial connections. The normal version of PuTTY with working serial support will looks like this:<br /> <br /> [[File:09-putty_serial.png|frame|center]]<br /> <br /> On Amiga (if you connect 2 Amigas by serial) you can use the old 68k Term 4.8:<br /> <br /> [[File:10-term48_serial.png|frame|center]]<br /> <br /> On Linux you can also use PuTTY or the well-known minicom.<br /> <br /> Whatever software is used, it is all about getting the debug data from your Amiga. Debug output is ASCII text data, so anything which can just grab information from your serial port and redirect it where you need it (console or file) will work. You can even write your own simple code which will receive data without the need for any terminal programs. But that's in theory, in practice it is better to use something which is already done.<br /> <br /> The settings which you need to use and which always works on any Amiga hardware from which you want to get your serial output are:<br /> <br /> baud: 115200 <br /> data bits: 8 <br /> stop bits: 1 <br /> parity: none <br /> flow control: none<br /> <br /> It may work with other settings (like different parity and flow control), but as it was pointed out before, on some hardware it may not work at all, on another it will not work as intended, so just these setting to do your first test. After all, you can always change your settings later and experiment after everything works.<br /> <br /> = How to redirect debug output to serial =<br /> <br /> By default, AmigaOS debug output is sent to a memory debug buffer and not to serial. This is done for simplicity. If something happens, especially bugs, then just type &quot;DumpDebugBuffer&quot; in a shell and it shows you what the debug output was. This is similar to using the Sashimi tool which redirects serial output to the console.<br /> <br /> For developers, it is usually best to output everything to the serial port so you need to switch the output to serial. There are 2 ways to do this: boot option in the firmware (U-Boot for Sams/Eyetech AmigaOnes, OpenFirmware for Pegasos2 and CFE for X1000) and the &quot;KDebug&quot; utility.<br /> <br /> == Firmware method ==<br /> <br /> Given there are so many different hardware platforms on which to run AmigaOS today, it should come as no surprise that they use different boot firmwares. AmigaOne-XE/MicroA1-C/Sam uses U-Boot, Pegasos2 uses OpenFirmware and the AmigaOne X1000 uses CFE. For all of them the boot menu options can be a bit different and you need to refer to the documentation which comes with the hardware. But in all cases you have a common variable called '''os4_commandline''' which you need to set. The name of that variable is the same for all the hardware platforms which support AmigaOS. Just the way the variable is setup varies.<br /> <br /> For example on Pegasos2 OpenFirmware, to redirect output to serial with the &quot;munge&quot; debug kernel option and debug level 7 in OF you do:<br /> <br /> Pegasos BIOS Extensions Copyright 2001-2004 by bplan GmbH.<br /> All rights Reserved.<br /> Auto-boot in 1 seconds - press ESC to abort, ENTER to boot: aborted<br /> ok#<br /> ok# setenv os4_commandline serial munge debuglevel=7<br /> <br /> and then boot AmigaOS.<br /> <br /> On AmigaOne X1000/CFE set munge, debuglevel to 4 and output to serial:<br /> <br /> setenv -p os4_commandline=&quot;serial munge debuglevel=4&quot;<br /> <br /> and then boot AmigaOS. For CFE if you are not using -p, then the variable is only saved for that session, not permanently.<br /> <br /> On Sam/AmigaOne U-Boot with the same munge, debuglevel=7 and serial redirect:<br /> <br /> setenv os4_commandline &quot;serial munge debuglevel=7&quot;<br /> saveenv<br /> <br /> In other words, use SetEnv to set the os4_commandline variable and then boot the OS. You can also verify what the variable is using the &quot;printenv&quot; command.<br /> <br /> Just so you are not confused, &quot;amigaboot.of&quot; (the code which first boots) is the component which parses the os4_commandline '''firmware variable''' and ''didn't'' parse any command line arguments. It only parses firmware variables and then passes them on to the kernel. If you try something like ''amigaboot.of os4_commandline = &quot;serial&quot;'', it will not work and will be ignored, the same as any other extra parameters you provide. So be sure that you use &quot;setenv&quot; and check via &quot;printenv&quot; that you set the variable correctly.<br /> <br /> == KDebug method ==<br /> <br /> KDebug is command line utility found in SYS:C which communicates with the AmigaOS kernel. With this utility you can redirect your output to serial or memory. It will override whatever you do with the os4_commandline firmware variable. This is very handy for setting different debug levels at the time you need it. For example, you may also put a command in S:User-Startup<br /> run &gt;NIL: kdebug &quot;debug level 5&quot;<br /> run &gt;NIL: kdebug &quot;console serial&quot;<br /> <br /> This will set the debug level to 5 and output via the serial port.<br /> <br /> {{Note|Quotation marks are mandatory when using the KDebug tool. What KDebug does is send whatever string you enter directly to the AmigaOS kernel for interpretation. The KDebug command itself does not parse the string.}}<br /> <br /> {{Note|KDebug method have higher priority. I.e. if you set your environment variable to some values, and then after os is boots use KDebug to change the settings, then they ''will'' be taken in account and previous one will be forgotten. The only thing that you can't enable/disable by KDebug is 'munge'.}}<br /> <br /> = Getting the Most out of Serial Debugging =<br /> <br /> To start with, you need to read the following articles:<br /> # [[Debug_Kernel|The Debug Kernel]]<br /> # [[Exec_Debug|Exec Debug]]<br /> <br /> To get the most out of serial debugging, developers should use what is called the debug kernel (named '''kernel.debug'''). The debug kernel provides you with more functionality compared with the release kernel at the cost of some execution speed. One thing provided is the ability to play with debug levels where you can choose how much &quot;system&quot; debug output you want to see. It's pretty easy to miss the fact that debug levels only work on debug kernels. Usually developers start to plays with levels, see no change, and start to think &quot;Why does it not work?&quot; It works, it is just that the kernel should be the debug one.<br /> <br /> And while the debug kernel does give you some debug functionality, it still may not cover everything. For example, tools like the old MungWall tool can do a bit more: debug kernel has only the &quot;munge&quot; feature but not the &quot;wall&quot; feature. Another example is MemGuard (which can be found on [http://www.os4depot.net OS4Depot]) adds additional debug capabilities on top of what the debug kernel provides and catches more difficult to find bugs.<br /> <br /> So, to get most of serial debugging, you need to use a combination: debug kernel with &quot;munge&quot; option enabled, MemGuard running in the background and set debug level to the value you find most informative. Usually 5 or 7 is enough but sometimes, when a bug is behaving very strangely, you can raise the value in the hope that you see something interesting.<br /> <br /> = If nothing works =<br /> <br /> Now on to troubleshooting. If you build/buy a cable, adapters and all the stuff, connect everything, fire up the terminal software, set up everything correctly and still nothing works, then:<br /> <br /> # Check the cable<br /> # Check the ports.<br /> # Check the cable again :)<br /> # Check program's settings and settings of the port if it USB to serial one. <br /> <br /> Be sure that for you have right settings and in the terminal software (especially the baud, flow control and parity).<br /> <br /> If you have a few '''spare''' connectors that you can use for troubleshooting, just solder a jumper between TX and RX (pins 2 and 3 on DB9). <br /> Then open a terminal program on the computer, set it up as described above, and turn &quot;Local Echo&quot; OFF. When Local Echo is OFF it does<br /> NOT show what you are typing, it only shows what comes in over the serial port.<br /> <br /> The &quot;loopback&quot; connector has TX and RX connected, so it will loop whatever you send back to you. Plug a female loopback directly into the serial port connector and you should see whatever you type, because it is being &quot;looped back&quot; through your test plug. Now take the loopback off, connect your cable, and attach a male loopback at the other end of the cable. If you can see your typing, then you are successfully going out the serial port, down your cable, then looping back up the cable and back into your port.. You get the idea. Having one male and one female &quot;loopback&quot; will let you test ALMOST every possible cable, connection, and software configuration.<br /> <br /> Desperate times: If you don't have any &quot;spare&quot; connectors or a soldering iron, a small paper clip can be used instead of a male loopback connector.. Just bend the clip and insert the ends into pins 2 and 3 of the cable end, and connect the other end to the serial port being tested. If the clip does not fit into the cable end, don't force it, find a smaller paper clip.<br /> <br /> The one thing that a loopback can NOT test is whether your cable is a &quot;Null Modem&quot; cable or not.<br /> The best way to check a cable is with a multimeter. Set it so that when you touch wires on different sides you will heard a &quot;beep&quot; if it connected. That setting usually looks like a little speaker. Check that all of the connections are as they should be. If you use null modem adapter on top of &quot;straight&quot; serial cable, then check it anyway, just in case, with the same meter. The meter lead probably won't fit inside the female connector pins. Another small paper clip helps with that.<br /> <br /> To work properly, (describe a null modem cable, assuming 9 pin to 9 pin):<br /> * Pin 2 on end A should connect to pin 3 on end B.<br /> * Pin 3 on end A should connect to pin 2 on end B.<br /> * Pin 5 on end A should connect to pin 5 on end B.<br /> <br /> If these three connections work, it should be enough to get you going.<br /> <br /> = Final words =<br /> <br /> While this topic is more or less an easy one, there wasn't a guide, until now, which describes everything from the beginning. What kind of cable you can use, how to build it, how to use USB to serial adapters, what settings should be used and what to do with it all. We hope that this guide will at least cover all the gaps and any developers told to &quot;use serial debugging&quot; will just read that article and will have no questions. Anyway, if you have any more info to add, or just found a wrong part somewhere, just send an email to kas1e@yandex.ru or use the [http://www.amigaos.net/Contact AmigaOS Contact Form] and we can update article.<br /> <br /> = Links =<br /> <br /> [1.] http://en.wikipedia.org/wiki/Serial_port<br /> [2.] http://en.wikipedia.org/wiki/Null_modem<br /> [3.] [[Debug_Kernel|Debug Kernel]]<br /> [4.] [[Exec_Debug|Exec Debug]]</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=Debug_Kernel&diff=7849 Debug Kernel 2015-01-22T22:05:23Z <p>Philippe Ferrucci: /* How to set it up */</p> <hr /> <div>== Introduction ==<br /> <br /> When you program AmigaOS, sooner or later you will need tools to help you debugging your applications (and not only yours) and find out why a program crashes or runs erratically. For that you have debuggers ([[GDB_for_Beginners|GDB]] and db101), small tools to operate with debug outputs and level of debugging (like KDebug, DumpDebugBuffer, etc.), memory trackers (like MemGuard and MemGuardian) and bunch of other small utilities and tricks which help you to do debugging. One of those tricks, which is little known, is the fact that a debug version of the standard AmigaOS kernel is publicly released ready to use for third party developers (or advanced users willing to help debugging applications).<br /> <br /> == What is &quot;debug kernel&quot; exactly? ==<br /> <br /> Debug kernel is the same kernel as the standard one, but with added code to help catching some of the most common programming errors. This additional code adds a slightly (yet non negligible) amount of bytes to the kernel size (around half a megabyte) and is slower. Thus it has been removed from the standard kernel for performance and optimization purposes and is generally not useful to the standard average user. Yet this debug kernel can prove itself to be very useful to programmers, especially it provides the following functionality:<br /> <br /> # Clobbering of succ/pred pointers when a Node is removed from a list.&lt;BR&gt;One common mistake when dealing with lists is to access successor and/or previous pointers from a removed node. While at first sight it may seems harmless it may reveal itself as a dreadful bug to spot because once a node has been removed from a list nothing guarantees you that the list has not be reworked/copied/reallocated or anything else. This will give you a bug that is very hard to reproduce or even non reproducible at all. As such one should NEVER access Succ/Prev pointers from a removed Node, instead if he needs to, he should access them prior the call to Remove(). To help spotting such errors the debug kernel will modify the ln_Succ/ln_Prev pointer to a given fixed invalid value thus the bug automatically becomes always reproducible. This will also help you spot the fact one is trying to free a Node twice.<br /> # &quot;Munge&quot; of memory. With this option the debug kernel will do additional tests on memory pointers. It will help spotting what really happened just by observing the DAR (or DEAR on 440ep and 460ex CPUs) value in the crash log:<br /> #* If the value is 0x00000000 (or thereabouts), then you have accessed a null pointer (and you will see 0xABADCAFE in one or more registers);<br /> #* If the value is 0xDEADBEEF or 0xFEFEBEEF then you have accessed some memory after it has been freed;<br /> #* If the value is 0xABADCAFE then you have accessed uninitialized memory;<br /> #* If the value is 0xCCCCCCCC (or thereabouts), then you have tried to free a Node a second time.<br /> <br /> When you want to catch all those problems which you can't catch by just simply running MemGuard on a release kernel then you should use the debug kernel. When developing software, it is recommended that you use the debug kernel.<br /> <br /> == How to set it up ==<br /> <br /> The kernel.debug file is already placed in the Kickstart directory with all the other kernel modules. By default this directory is &quot;SYS:Kickstart/&quot;.<br /> <br /> The preferred way to use the debug kernel is to edit your kicklayout file, duplicate the current layout and in this duplicate modify the line pointing to &quot;kernel&quot; so it points to &quot;kernel.debug&quot;, do not forget to change the label associated with this new layout by adding 'debug' or something. This way you will be able to choose which configuration you want to boot at any time.<br /> <br /> Once you have setup the use of the debug kernel, you must also add some options to the kernel. Basically in order to activate the munge option of the debug kernel you must set the variable &quot;os4_commandline&quot; adds the keyword &quot;munge&quot;. This part depends on your platform firmware, please report to your documentation to know how to do it, but you have to do something like &quot;setenv os4_commandline munge&quot; or &quot;setenv os4_commandline=munge&quot; (depends on your firmware), if os4_commandline is already set with another value you can concatenate using space e.g. os4_commandline 'serial munge' to have the debug output to serial port and the munge option activated.<br /> <br /> {{Note|text=Do not confuse environment variables with command line parameters. You cannot set kernel options via amigaboot.of like &quot;amigaboot.of os4_commandline 'serial'&quot; and the extra parameters will be just ignored. Instead you must set those variables via the &quot;setenv&quot; command in the firmware and then amigaboot.of will parse them.}}<br /> <br /> The following kernel parameters are available:<br /> <br /> ; serial<br /> : Outputs all debug via the serial port, instead of using a memory buffer.<br /> <br /> ; baudrate [N]<br /> : Sets the serial port baud rate to N.<br /> <br /> ; debuglevel [N]<br /> : Sets the debuglevel to level N.<br /> : The debug level is the amount of information that should be output by the debug kernel.<br /> : Debug levels range between 0 to 20 with 0 being no debug, 5 moderate output (all warnings are 5 or lower), 10 being lots of output, and 15 being an insane amount of output (fault conditions from kernel functions are displayed), and 20 being a ludicrous amount of output (entry and exit to functions will be logged).<br /> : Note: higher levels are possible, but will produce too much output to be useful.<br /> <br /> ; nofpuemu<br /> : Sets the AttnFlags in ExecBase to a 68020 without an FPU.<br /> <br /> ; munge<br /> : Munges (fills) freed memory with a recognisable value so that illegal memory accesses can be found more easily when using both the debug and non-debug kernels.<br /> : In other words, no valid data will persist past any deallocation function, so if someone reads from memory that has just been freed, they are likely to get a pointer address to a region that will cause an exception when accessed, instead of its previous contents. The munging value written to freed memory is architecture dependant and allocation type dependant, here are some of the values you may encounter: 0xfefecafe, 0xabadcafe, 0xfefeabad, 0xabadabad, 0xfefebeef, 0xdeadbeef.<br /> : Note: This argument does nothing on a release kernel.<br /> <br /> {{Note|text=It is strongly recommended that you do not rename the kernel.debug file.}}<br /> <br /> [[Category:Debug]]</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=Debug_Kernel&diff=7848 Debug Kernel 2015-01-21T21:22:00Z <p>Philippe Ferrucci: /* How to set it up */</p> <hr /> <div>== Introduction ==<br /> <br /> When you program AmigaOS, sooner or later you will need tools to help you debugging your applications (and not only yours) and find out why a program crashes or runs erratically. For that you have debuggers ([[GDB_for_Beginners|GDB]] and db101), small tools to operate with debug outputs and level of debugging (like KDebug, DumpDebugBuffer, etc.), memory trackers (like MemGuard and MemGuardian) and bunch of other small utilities and tricks which help you to do debugging. One of those tricks, which is little known, is the fact that a debug version of the standard AmigaOS kernel is publicly released ready to use for third party developers (or advanced users willing to help debugging applications).<br /> <br /> == What is &quot;debug kernel&quot; exactly? ==<br /> <br /> Debug kernel is the same kernel as the standard one, but with added code to help catching some of the most common programming errors. This additional code adds a slightly (yet non negligible) amount of bytes to the kernel size (around half a megabyte) and is slower. Thus it has been removed from the standard kernel for performance and optimization purposes and is generally not useful to the standard average user. Yet this debug kernel can prove itself to be very useful to programmers, especially it provides the following functionality:<br /> <br /> # Clobbering of succ/pred pointers when a Node is removed from a list.&lt;BR&gt;One common mistake when dealing with lists is to access successor and/or previous pointers from a removed node. While at first sight it may seems harmless it may reveal itself as a dreadful bug to spot because once a node has been removed from a list nothing guarantees you that the list has not be reworked/copied/reallocated or anything else. This will give you a bug that is very hard to reproduce or even non reproducible at all. As such one should NEVER access Succ/Prev pointers from a removed Node, instead if he needs to, he should access them prior the call to Remove(). To help spotting such errors the debug kernel will modify the ln_Succ/ln_Prev pointer to a given fixed invalid value thus the bug automatically becomes always reproducible. This will also help you spot the fact one is trying to free a Node twice.<br /> # &quot;Munge&quot; of memory. With this option the debug kernel will do additional tests on memory pointers. It will help spotting what really happened just by observing the DAR (or DEAR on 440ep and 460ex CPUs) value in the crash log:<br /> #* If the value is 0x00000000 (or thereabouts), then you have accessed a null pointer (and you will see 0xABADCAFE in one or more registers);<br /> #* If the value is 0xDEADBEEF or 0xFEFEBEEF then you have accessed some memory after it has been freed;<br /> #* If the value is 0xABADCAFE then you have accessed uninitialized memory;<br /> #* If the value is 0xCCCCCCCC (or thereabouts), then you have tried to free a Node a second time.<br /> <br /> When you want to catch all those problems which you can't catch by just simply running MemGuard on a release kernel then you should use the debug kernel. When developing software, it is recommended that you use the debug kernel.<br /> <br /> == How to set it up ==<br /> <br /> The kernel.debug file is already placed in the Kickstart directory with all the other kernel modules. By default this directory is &quot;SYS:Kickstart/&quot;.<br /> <br /> The preferred way to use the debug kernel is to edit your kicklayout file, duplicate the current layout and in this duplicate modify the line pointing to &quot;kernel&quot; so it points to &quot;kernel.debug&quot;, do not forget to change the label associated with this new layout by adding 'debug' or something. This way you will be able to choose which configuration you want to boot at any time.<br /> <br /> Once you have setup the use of the debug kernel, you must also add some options to the kernel. Basically in order to activate the munge option of the debug kernel you must set the variable &quot;os4_commandline&quot; adds the keyword &quot;munge&quot;. This part depends on your platform firmware, please report to your documentation to know how to do it, but you have to do something like &quot;setenv os4_commandline munge&quot; or &quot;setenv os4_commandline=munge&quot; (depends on your firmware), if os4_commandline is already set with another value you can concatenate using space e.g. os4_commandline 'serial munge' to have the debug output to serial port and the munge option activated.<br /> <br /> {{Note|text=Do not confuse environment variables with command line parameters. You cannot set kernel options via amigaboot.of like &quot;amigaboot.of os4_commandline 'serial'&quot; and the extra parameters will be just ignored. Instead you must set those variables via the &quot;setenv&quot; command in the firmware and then amigaboot.of will parse them.}}<br /> <br /> The following kernel parameters are available:<br /> <br /> ; serial<br /> : Outputs all debug via the serial port, instead of using a memory buffer.<br /> <br /> ; baudrate [N]<br /> : Sets the serial port baud rate to N.<br /> <br /> ; debuglevel [N]<br /> : Sets the debuglevel to level N.<br /> : The debug level is the amount of information that should be output by the debug kernel.<br /> : Debug levels range between 0 to 20 with 0 being no debug, 5 moderate output (all warnings are 5 or lower), 10 being lots of output, and 15 being an insane amount of output (fault conditions from kernel functions are displayed), and 20 being a ludicrous amount of output (entry and exit to functions will be logged).<br /> : Note: higher levels are possible, but will produce too much output to be useful.<br /> <br /> ; nofpuemu<br /> : Sets the AttnFlags in ExecBase to a 68020 without an FPU.<br /> <br /> ; munge<br /> : Munges (fills) freed memory with a recognisable value so that memory trashing can be found more easily when using a debug kernel.<br /> : In other words, no valid data will persist past any deallocation function, so if someone reads from memory that has just been freed, they are likely to get a pointer address to an area that will cause a DSI exception when accessed, instead of its previous contents.<br /> : On the Sam440 and Sam460, the longword munge value is 0xfefecafe. On other machines it is 0xabadcafe.<br /> : Note: This argument does nothing on a release kernel.<br /> <br /> {{Note|text=It is strongly recommended that you do not rename the kernel.debug file.}}<br /> <br /> [[Category:Debug]]</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=Installation_Utility&diff=7840 Installation Utility 2014-11-30T00:41:32Z <p>Philippe Ferrucci: /* GUI's */ various arguments added, looking at the sources</p> <hr /> <div>= How the installer works =<br /> <br /> == Basic concept ==<br /> <br /> The installation utility executes a python script that sets up the installation. In addition to standard Python commands the installation utility provides a module called &quot;installer&quot; and an interface to it. Using this interface you can create the different pages that can be found in almost all installation processes: a welcome page, a displayed licence page, a selection page, an installation page and finally a finish page.<br /> In the end, there are only a few script commands required.<br /> <br /> == Running an installation script ==<br /> <br /> === From the command line ===<br /> <br /> In order to run an installation from the command line, invoke the installation utility giving your script file as an argument and if you want a logo to be displayed at the top of the window:<br /> <br /> &lt;pre&gt;<br /> &quot;SYS:Utilities/Installation utility&quot; PACKAGE=myscript.py LOGO=mylogo.png<br /> &lt;/pre&gt;<br /> Note: the logo will be displayed all along the installation process.<br /> <br /> ''Note2: right now you need to set these argument names with capital letters, as shown above.''<br /> <br /> === From the Workbench ===<br /> <br /> Add a project icon to your script and use ''SYS:Utilities/Installation utility'' as the default tool.<br /> <br /> ==== Tooltypes ====<br /> <br /> * PACKAGE (Default: ''package.py'')<br /> <br /> This tooltype is used to specify the script name to execute. It is useful if you want to use a standalone icon that will open a script with a different name or in another directory.<br /> <br /> * LOGO<br /> <br /> You can use this tooltype to specify an image name to use in the installer window.<br /> <br /> = Example script =<br /> <br /> A minimal install script looks like this:<br /> <br /> &lt;pre&gt;<br /> # Simple, basic installation script<br /> from installer import *<br /> <br /> # These will be used for the first page (welcome) and last page (finish)<br /> welcomeText = &quot;This is a welcome text, displayed at the first page&quot;<br /> finishText = &quot;This is the finish message&quot;<br /> <br /> # Define the Welcome page<br /> welcomePage = NewPage(WELCOME)<br /> SetString(welcomePage, &quot;message&quot;, welcomeText)<br /> <br /> # Define the License page. The user must accept this license to continue the install process.<br /> # The license text will be read from a text file called &quot;license.txt&quot; and will be displayed on the page.<br /> licensePage = NewPage(LICENSE)<br /> <br /> # Define a page to select the installation directory<br /> destinationPage = NewPage(DESTINATION)<br /> SetString(destinationPage, &quot;message&quot;, &quot;Please indicate where you want to install the files .&quot;)<br /> SetString(destinationPage, &quot;destination&quot;, &quot;SYS:&quot;)<br /> <br /> # Define a directory to be copied to the destination<br /> filePack = AddPackage (FILEPACKAGE,<br /> name = &quot;Full directory&quot;,<br /> description = &quot;Directory to copy as-is in the destination&quot;,<br /> files = [&quot;data&quot;],<br /> optional = False<br /> )<br /> <br /> # Define a progress page that is shown during the installation<br /> installPage = NewPage(INSTALL)<br /> <br /> # Create a &quot;finish&quot; page.<br /> finalPage = NewPage(FINISH)<br /> SetString(finalPage, &quot;message&quot;, finishText)<br /> <br /> # Finally, this runs the installation.<br /> RunInstaller()<br /> &lt;/pre&gt;<br /> <br /> = Python Interface =<br /> <br /> == Introduction ==<br /> <br /> The installer is entirely programmed in Python. For this purpose, it provides a Python module called 'installer' that serves as a functional interface to the GUI. The entire GUI is build out of pages. Pages present different kind of information to the user. The installation can be navigated with a pair of forward/backward buttons to visit each page in turn. Certain pages (notably the INSTALL page) will trigger the installation process itself, although the interface is flexible enough to make an installation that is entirely driven by the Python script. A minimal setup function will create a &quot;default&quot; layout of pages for an installer. The basic is to have a single archive that is installed into a destination drawer created on the disk - about 90% of all installers will do exactly this. Therefore a lot of the mechanics involved in this type of installer is automated.<br /> <br /> == Python Functions in the installer package ==<br /> <br /> === NewPage ===<br /> <br /> This function creates a new page and returns its page number for later reference. The only argument to the function is the type of page to create. Possible values are:<br /> <br /> ; WELCOME<br /> : A message page, usually used for displaying a &quot;welcome&quot; message, although other uses are perfectly possible as well.<br /> : ''Note:'' this page is mandatory.<br /> <br /> ; FINISH<br /> : A message page that is specifically targeted at closing the installation. This page automatically gets the &quot;finish&quot; attribute set to make the installation change the &quot;cancel&quot; to the &quot;finish&quot; button.<br /> <br /> ; DESTINATION<br /> : A page to select a directory to serve as the target for the installation.<br /> : ''Note:'' this page is mandatory.<br /> <br /> ; INSTALL<br /> : The presence of this page automatically triggers the installation of the selected packages.<br /> <br /> ; GUI<br /> : A page where GUI elements can be added and controlled via a Python handler.<br /> <br /> ; PROCESSING<br /> : A page to display a simple progress bar for doing some Python-scripted processing.<br /> <br /> ; LICENSE<br /> : A brickwall page that displays a license agreement that only lets the user continue after accepting the license.<br /> : ''Note:'' the installation utility will look for a text file called &quot;license_''languagename''.language.txt&quot;, if not found, it will look for a file called &quot;license.txt&quot;.<br /> <br /> ; README<br /> : A page that displays a text file from disk for reference/README purposes.<br /> <br /> If the page cannot be generated, an OSError exception is raised.<br /> <br /> === GotoPage ===<br /> <br /> This function accepts a single argument, the page to display. This function should rarely be needed.<br /> <br /> === SetString, SetInteger, SetObject ===<br /> <br /> This function sets a variable of the specified type on a page. It accepts three parameters:<br /> * The Page number to set the variable on<br /> * The name of the variable<br /> * The variable content.<br /> <br /> === GetString, GetInteger, GetObject ===<br /> <br /> These functions are the reverse of the above - they read a variable from the page specified as its first argument and the name specified as the second argument. They return a default value if the name was not found.<br /> <br /> === RunInstaller ===<br /> <br /> This function runs the installer's main loop, and needs to be the last command in an installation. Any subsequent scripting is done via handlers connected to the pages.<br /> <br /> === AddPackage ===<br /> <br /> This function adds a package to the list of installable packages. The function's interface uses keywords to make it more readable. The keywords are:<br /> <br /> ; type<br /> : The type of package. This can be either FILEPACKAGE, ARCHIVEPACKAGE or HANDLERPACKAGE. A file package copies a list of files to the destination. An archive package unpacks a list of archives at the destination. Finally, a handler package is an abstract package that executes a handler when it is installed or upon certain actions.<br /> : This argument MUST be given.<br /> <br /> ; name<br /> : A string that specifies the name of the package. This name is presented to the user of the installer on a PACKAGESELECT page.<br /> : A name should be given. It defaults to an empty string.<br /> <br /> ; description<br /> : A textual description of the package. It is presented to the user next to the package list on a PACKAGESELECT page if the package is selected in the package list.<br /> : The description may be empty, although it is consider bad style. It defaults to an empty string.<br /> <br /> ; optional<br /> : A boolean value indicating whether the package is optional to install or required to be installed. A value of True means the package is optional.<br /> : Default is True (package is optional)<br /> <br /> ; selected<br /> : A boolean indicating whether the package should be pre-selected or not. If True, the package is selected the first time the PACKAGESELECT page is entered.<br /> : Default is True (package is selected), although the user might deselect the package on a PACKAGESELECT page<br /> <br /> ; diskspace<br /> : An integer value specifying the number of bytes the package occupies after installation. If a zero size is given (or the parameter is omitted) the installer tries to figure out the size requirements automatically, but be warned this might be a time consuming process.<br /> : Defaults to zero (try to figure out yourself)<br /> <br /> ; featuregroup<br /> : An integer bitmask giving one bit of each feature group defined. A one bit indicates this package is part of the group, while a zero bit indicates it isn't.<br /> : Defaults to zero (not in any feature group)<br /> <br /> ; alternatepath<br /> : Specifies an alternative installation path. For example, some files might need to be installed into LIBS: instead of the usual destination. This feature should be used with care.<br /> : Defaults to None (i.e. no alternate path)<br /> <br /> ; files<br /> : A list of strings, each string representing one file associated with this package. The interpretation of these files depend on the package type:<br /> :: ARCHIVEPACKAGE: each file is an archive that is supposed to be extracted into the destination.<br /> :: HANDLERPACKAGE: The strings are not interpreted in any way, it is up to the handler to do that.<br /> :: FILEPACKAGE: Each string stands for a file or directory to be copied. Files are straight copies, while directory names are interpreted slightly different: if a directory name is given, that entire directory is copied to the destination, including the directory itself. For example, if you specify &quot;System&quot; then the destination directory will include a &quot;System&quot; directory. On the other hand, if you specify it as &quot;System/&quot; with a trailing slash, the content of the directory will be copied but not the directory itself, i.e. the destination directory would contain all the file and directories in the &quot;System&quot; directory but not the directory itself.<br /> :: ''Note:'' directory/file names must be relative to the current directory i.e. where the installer is executed. You cannot use here a complete path name with the volume name like ''RAM:mydir''.<br /> : The default is an empty list.<br /> <br /> The result of this function is a package number, which can be used subsequently to adjust package settings or query certain features.<br /> <br /> == GUI's ==<br /> <br /> GUI's must be created from scratch using a procedural interface. The following procedures deal with creating and handling the user interface. In general, the user interface must be generated once and cannot be changed afterwards (with exceptions, see below).<br /> <br /> A GUI is started with a call to StartGUI(page_number). This will start to create a GUI on the indicated page number, and all subsequent calls will add to this GUI until EndGUI() is called. If the indicated page number is invalid or is not a GUI page, ever subsequent calls are ignored until a new StartGUI with a valid page number is called.<br /> <br /> Immediately after the call, a single GUI object might be defined. In almost all cases, this will be a group to hold a number of GUI elements. Groups are defined with the BeginGroup and EndGroup calls.<br /> <br /> BeginGroup takes the following keyword arguments:<br /> ; orientation<br /> : This specifies whether the children of this group are laid out vertically or horizontally. By default the layout is vertically.<br /> ; label<br /> : A short text string that can be displayed as a label for this group. The label is only used if a frame other than NONE_FRAME is specified. By default no label is used.<br /> ; frame<br /> : One of the constants NONE_FRAME, THIN_FRAME, BUTTON_FRAME, GROUP_FRAME, FIELD_FRAME, DROPBOX_FRAME, SBAR_HORIZ_FRAME, SBAR_VERT_FRAME, BOX_FRAME, STANDARD_FRAME. They directly correspond to the bevel styles of bevel.image. Defaults to NONE_FRAME.<br /> ; weight<br /> : An integer defining the weighted width or height of this group. This corresponds to layout.gadget's CHILD_WeightedWidth or CHILD_WeightedHeight tags, depending on the layout direction.<br /> <br /> EndGroup has no parameters and automatically terminates the last group opened by BeginGroup.<br /> <br /> User interface elements are added with the following calls. All of these return an ID number.<br /> <br /> === AddLabel ===<br /> <br /> This call adds a text label, with selectable frame. The following keyword arguments are supported:<br /> ; label<br /> : A string that specifies the label to be displayed. Default is empty, although an empty label doesn't make much sense<br /> <br /> ; frame<br /> : A frame to put around the label.<br /> <br /> ; weight<br /> : The weight of the label, as explained above.<br /> <br /> ; align<br /> : Text alignment to use for the label. Possible values are: ALIGN_LEFT, ALIGN_RIGHT, ALIGN_CENTER, ALIGN_BLOCK<br /> <br /> === AddString ===<br /> <br /> ; label<br /> : A string that specifies the label to be displayed. Default is empty, although an empty label doesn't make much sense<br /> <br /> ; value<br /> : Value to use as the default string<br /> <br /> ; weight<br /> : The weight of the label, as explained above.<br /> <br /> ; handler<br /> : A Python callable object that is invoked when the string field is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id) where page_number is the page number of the GUI page and element_id is the element id returned by this call.<br /> <br /> === AddButton ===<br /> <br /> This call adds a push button object to the current group. The function supports the following keyword arguments:<br /> ; label<br /> : A string specifying the label to be displayed within the button. Defaults to an empty label.<br /> <br /> ; frame<br /> : One of the constants mentioned above for the group. Defaults to BUTTON_FRAME.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; onclick<br /> : A Python callable object that is invoked when the button is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id) where page_number is the page number of the GUI page and element_id is the element id returned by this call.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddCheckBox ===<br /> <br /> This call adds a checkbox object to the GUI. The following keyword arguments are valid:<br /> <br /> ; label<br /> : A string that appears as a label to the right of the checkbox. Defaults to an empty label.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; checked<br /> : An integer that specifies whether the checkbox is initially checked or not. A zero means the checkbox is clear, any other value says the box is checked.<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the checkbox is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, state) where page_number and element_id are the same as above, and state is a 0 if the user just unchecked the checkbox, or a 1 is it was just checked.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddRadioButton ===<br /> <br /> This call adds a set of mutually exclusive radio buttons. The following keyword arguments are valid:<br /> <br /> ; label list<br /> : A list of Python strings, with each of these strings appearing as a choice on the Radio buttons. This parameter is required.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; selected<br /> : The number of the button initially selected. Defaults to the first button (0).<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the radio button is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the button number that was selected.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddChooser ===<br /> <br /> This function adds a chooser gadget to the GUI. The following keyword arguments are valid:<br /> <br /> ; label<br /> : A test string to be displayed in the chooser in pop-up mode (see below). Defaults to an empty string, and is not used for drop-down mode.<br /> <br /> ; choices<br /> : A list of text strings to be displayed as choices for the chooser. This argument is mandatory.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; selected<br /> : The number of the currently visible item in drop-down mode. Defaults to 0.<br /> <br /> ; mode<br /> : One of the constants CHOOSER_POPUP or CHOOSER_DROPDOWN. This corresponds to the chooser.gadget CHOOSER_PopUp and CHOOSER_DropDown tag items.<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the chooser is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the title number that was selected.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddSpace ===<br /> <br /> This call adds a bit of space to the GUI. It accepts only one parameter:<br /> <br /> ; weight<br /> : An integer specifying the weight of the space. Defaults to 1.<br /> <br /> The call does not return a value. Space does not have any variables.<br /> <br /> == User Interface Settings ==<br /> <br /> In order to change some aspects of user interface elements (like the selection status of a checkbox) or read their current state, two functions exist called GetUIAttr and SetUIAttr.<br /> <br /> The former reads an attribute from an identified user interface element (identified by the page number and element id) while the latter sets (and updates the on-screen representation) of an equally identified element.<br /> <br /> A number of attributes can be set and gotten from UI elements; some of them are shared among more than one element type, while others are specific. The following list names the attributes:<br /> <br /> ; GUI_LABEL (string)<br /> : The label displayed on a UI element.<br /> : Applies to BUTTON, LABEL, GROUP, CHECKBOX<br /> <br /> ; GUI_SELECTED (integer)<br /> : The selected item in a chooser or radio button.<br /> : Applies to CHOOSER and RADIOBUTTON<br /> <br /> ; GUI_CHECKED (integer)<br /> : Whether the checkbox checkmark is set or not.<br /> : Applies to CHECKBOX<br /> <br /> ; GUI_ONCLICK (Python callable)<br /> : The handler invoked when the UI element is activated.<br /> : Applies to CHOOSER, BUTTON, LABEL, GROUP, CHECKBOX, RADIOBUTTON<br /> <br /> The GetUIAttr function's prototype looks like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> result = GetUIAttr(page_nr, id, attr)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> page_nr and id identify the object by giving the GUI's page number and the element id returned by the creation call. The attr parameter is one of the attributes given above. Valid parameters for attr are GUI_SELECTED, GUI_CHECKED and GUI_ONCLICK.<br /> <br /> For SetUIAttr, the prototype looks like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> SetUIAttr(page_nr, id, attr, value)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> page_nr and id and attr are the same as above. The value parameter specifies the new value of the attribute, and must match the type for the attribute or the call will have no effect.<br /> <br /> = Hints =<br /> <br /> * See the AmigaOS 4 installation script on the AmigaOS Installation CD. It is a big script full of functions. Take it as example and experiment.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=Installation_Utility&diff=7839 Installation Utility 2014-11-30T00:28:32Z <p>Philippe Ferrucci: /* AddLabel */</p> <hr /> <div>= How the installer works =<br /> <br /> == Basic concept ==<br /> <br /> The installation utility executes a python script that sets up the installation. In addition to standard Python commands the installation utility provides a module called &quot;installer&quot; and an interface to it. Using this interface you can create the different pages that can be found in almost all installation processes: a welcome page, a displayed licence page, a selection page, an installation page and finally a finish page.<br /> In the end, there are only a few script commands required.<br /> <br /> == Running an installation script ==<br /> <br /> === From the command line ===<br /> <br /> In order to run an installation from the command line, invoke the installation utility giving your script file as an argument and if you want a logo to be displayed at the top of the window:<br /> <br /> &lt;pre&gt;<br /> &quot;SYS:Utilities/Installation utility&quot; PACKAGE=myscript.py LOGO=mylogo.png<br /> &lt;/pre&gt;<br /> Note: the logo will be displayed all along the installation process.<br /> <br /> ''Note2: right now you need to set these argument names with capital letters, as shown above.''<br /> <br /> === From the Workbench ===<br /> <br /> Add a project icon to your script and use ''SYS:Utilities/Installation utility'' as the default tool.<br /> <br /> ==== Tooltypes ====<br /> <br /> * PACKAGE (Default: ''package.py'')<br /> <br /> This tooltype is used to specify the script name to execute. It is useful if you want to use a standalone icon that will open a script with a different name or in another directory.<br /> <br /> * LOGO<br /> <br /> You can use this tooltype to specify an image name to use in the installer window.<br /> <br /> = Example script =<br /> <br /> A minimal install script looks like this:<br /> <br /> &lt;pre&gt;<br /> # Simple, basic installation script<br /> from installer import *<br /> <br /> # These will be used for the first page (welcome) and last page (finish)<br /> welcomeText = &quot;This is a welcome text, displayed at the first page&quot;<br /> finishText = &quot;This is the finish message&quot;<br /> <br /> # Define the Welcome page<br /> welcomePage = NewPage(WELCOME)<br /> SetString(welcomePage, &quot;message&quot;, welcomeText)<br /> <br /> # Define the License page. The user must accept this license to continue the install process.<br /> # The license text will be read from a text file called &quot;license.txt&quot; and will be displayed on the page.<br /> licensePage = NewPage(LICENSE)<br /> <br /> # Define a page to select the installation directory<br /> destinationPage = NewPage(DESTINATION)<br /> SetString(destinationPage, &quot;message&quot;, &quot;Please indicate where you want to install the files .&quot;)<br /> SetString(destinationPage, &quot;destination&quot;, &quot;SYS:&quot;)<br /> <br /> # Define a directory to be copied to the destination<br /> filePack = AddPackage (FILEPACKAGE,<br /> name = &quot;Full directory&quot;,<br /> description = &quot;Directory to copy as-is in the destination&quot;,<br /> files = [&quot;data&quot;],<br /> optional = False<br /> )<br /> <br /> # Define a progress page that is shown during the installation<br /> installPage = NewPage(INSTALL)<br /> <br /> # Create a &quot;finish&quot; page.<br /> finalPage = NewPage(FINISH)<br /> SetString(finalPage, &quot;message&quot;, finishText)<br /> <br /> # Finally, this runs the installation.<br /> RunInstaller()<br /> &lt;/pre&gt;<br /> <br /> = Python Interface =<br /> <br /> == Introduction ==<br /> <br /> The installer is entirely programmed in Python. For this purpose, it provides a Python module called 'installer' that serves as a functional interface to the GUI. The entire GUI is build out of pages. Pages present different kind of information to the user. The installation can be navigated with a pair of forward/backward buttons to visit each page in turn. Certain pages (notably the INSTALL page) will trigger the installation process itself, although the interface is flexible enough to make an installation that is entirely driven by the Python script. A minimal setup function will create a &quot;default&quot; layout of pages for an installer. The basic is to have a single archive that is installed into a destination drawer created on the disk - about 90% of all installers will do exactly this. Therefore a lot of the mechanics involved in this type of installer is automated.<br /> <br /> == Python Functions in the installer package ==<br /> <br /> === NewPage ===<br /> <br /> This function creates a new page and returns its page number for later reference. The only argument to the function is the type of page to create. Possible values are:<br /> <br /> ; WELCOME<br /> : A message page, usually used for displaying a &quot;welcome&quot; message, although other uses are perfectly possible as well.<br /> : ''Note:'' this page is mandatory.<br /> <br /> ; FINISH<br /> : A message page that is specifically targeted at closing the installation. This page automatically gets the &quot;finish&quot; attribute set to make the installation change the &quot;cancel&quot; to the &quot;finish&quot; button.<br /> <br /> ; DESTINATION<br /> : A page to select a directory to serve as the target for the installation.<br /> : ''Note:'' this page is mandatory.<br /> <br /> ; INSTALL<br /> : The presence of this page automatically triggers the installation of the selected packages.<br /> <br /> ; GUI<br /> : A page where GUI elements can be added and controlled via a Python handler.<br /> <br /> ; PROCESSING<br /> : A page to display a simple progress bar for doing some Python-scripted processing.<br /> <br /> ; LICENSE<br /> : A brickwall page that displays a license agreement that only lets the user continue after accepting the license.<br /> : ''Note:'' the installation utility will look for a text file called &quot;license_''languagename''.language.txt&quot;, if not found, it will look for a file called &quot;license.txt&quot;.<br /> <br /> ; README<br /> : A page that displays a text file from disk for reference/README purposes.<br /> <br /> If the page cannot be generated, an OSError exception is raised.<br /> <br /> === GotoPage ===<br /> <br /> This function accepts a single argument, the page to display. This function should rarely be needed.<br /> <br /> === SetString, SetInteger, SetObject ===<br /> <br /> This function sets a variable of the specified type on a page. It accepts three parameters:<br /> * The Page number to set the variable on<br /> * The name of the variable<br /> * The variable content.<br /> <br /> === GetString, GetInteger, GetObject ===<br /> <br /> These functions are the reverse of the above - they read a variable from the page specified as its first argument and the name specified as the second argument. They return a default value if the name was not found.<br /> <br /> === RunInstaller ===<br /> <br /> This function runs the installer's main loop, and needs to be the last command in an installation. Any subsequent scripting is done via handlers connected to the pages.<br /> <br /> === AddPackage ===<br /> <br /> This function adds a package to the list of installable packages. The function's interface uses keywords to make it more readable. The keywords are:<br /> <br /> ; type<br /> : The type of package. This can be either FILEPACKAGE, ARCHIVEPACKAGE or HANDLERPACKAGE. A file package copies a list of files to the destination. An archive package unpacks a list of archives at the destination. Finally, a handler package is an abstract package that executes a handler when it is installed or upon certain actions.<br /> : This argument MUST be given.<br /> <br /> ; name<br /> : A string that specifies the name of the package. This name is presented to the user of the installer on a PACKAGESELECT page.<br /> : A name should be given. It defaults to an empty string.<br /> <br /> ; description<br /> : A textual description of the package. It is presented to the user next to the package list on a PACKAGESELECT page if the package is selected in the package list.<br /> : The description may be empty, although it is consider bad style. It defaults to an empty string.<br /> <br /> ; optional<br /> : A boolean value indicating whether the package is optional to install or required to be installed. A value of True means the package is optional.<br /> : Default is True (package is optional)<br /> <br /> ; selected<br /> : A boolean indicating whether the package should be pre-selected or not. If True, the package is selected the first time the PACKAGESELECT page is entered.<br /> : Default is True (package is selected), although the user might deselect the package on a PACKAGESELECT page<br /> <br /> ; diskspace<br /> : An integer value specifying the number of bytes the package occupies after installation. If a zero size is given (or the parameter is omitted) the installer tries to figure out the size requirements automatically, but be warned this might be a time consuming process.<br /> : Defaults to zero (try to figure out yourself)<br /> <br /> ; featuregroup<br /> : An integer bitmask giving one bit of each feature group defined. A one bit indicates this package is part of the group, while a zero bit indicates it isn't.<br /> : Defaults to zero (not in any feature group)<br /> <br /> ; alternatepath<br /> : Specifies an alternative installation path. For example, some files might need to be installed into LIBS: instead of the usual destination. This feature should be used with care.<br /> : Defaults to None (i.e. no alternate path)<br /> <br /> ; files<br /> : A list of strings, each string representing one file associated with this package. The interpretation of these files depend on the package type:<br /> :: ARCHIVEPACKAGE: each file is an archive that is supposed to be extracted into the destination.<br /> :: HANDLERPACKAGE: The strings are not interpreted in any way, it is up to the handler to do that.<br /> :: FILEPACKAGE: Each string stands for a file or directory to be copied. Files are straight copies, while directory names are interpreted slightly different: if a directory name is given, that entire directory is copied to the destination, including the directory itself. For example, if you specify &quot;System&quot; then the destination directory will include a &quot;System&quot; directory. On the other hand, if you specify it as &quot;System/&quot; with a trailing slash, the content of the directory will be copied but not the directory itself, i.e. the destination directory would contain all the file and directories in the &quot;System&quot; directory but not the directory itself.<br /> :: ''Note:'' directory/file names must be relative to the current directory i.e. where the installer is executed. You cannot use here a complete path name with the volume name like ''RAM:mydir''.<br /> : The default is an empty list.<br /> <br /> The result of this function is a package number, which can be used subsequently to adjust package settings or query certain features.<br /> <br /> == GUI's ==<br /> <br /> GUI's must be created from scratch using a procedural interface. The following procedures deal with creating and handling the user interface. In general, the user interface must be generated once and cannot be changed afterwards (with exceptions, see below).<br /> <br /> A GUI is started with a call to StartGUI(page_number). This will start to create a GUI on the indicated page number, and all subsequent calls will add to this GUI until EndGUI() is called. If the indicated page number is invalid or is not a GUI page, ever subsequent calls are ignored until a new StartGUI with a valid page number is called.<br /> <br /> Immediately after the call, a single GUI object might be defined. In almost all cases, this will be a group to hold a number of GUI elements. Groups are defined with the BeginGroup and EndGroup calls.<br /> <br /> BeginGroup takes the following keyword arguments:<br /> ; orientation<br /> : This specifies whether the children of this group are laid out vertically or horizontally. By default the layout is vertically.<br /> ; label<br /> : A short text string that can be displayed as a label for this group. The label is only used if a frame other than NONE_FRAME is specified. By default no label is used.<br /> ; frame<br /> : One of the constants NONE_FRAME, THIN_FRAME, BUTTON_FRAME, GROUP_FRAME, FIELD_FRAME, DROPBOX_FRAME, SBAR_HORIZ_FRAME, SBAR_VERT_FRAME, BOX_FRAME, STANDARD_FRAME. They directly correspond to the bevel styles of bevel.image. Defaults to NONE_FRAME.<br /> ; weight<br /> : An integer defining the weighted width or height of this group. This corresponds to layout.gadget's CHILD_WeightedWidth or CHILD_WeightedHeight tags, depending on the layout direction.<br /> <br /> EndGroup has no parameters and automatically terminates the last group opened by BeginGroup.<br /> <br /> User interface elements are added with the following calls. All of these return an ID number.<br /> <br /> === AddLabel ===<br /> <br /> This call adds a text label, with selectable frame. The following keyword arguments are supported:<br /> ; label<br /> : A string that specifies the label to be displayed. Default is empty, although an empty label doesn't make much sense<br /> <br /> ; frame<br /> : A frame to put around the label.<br /> <br /> ; weight<br /> : The weight of the label, as explained above.<br /> <br /> ; align<br /> : Text alignment to use for the label. Possible values are: ALIGN_LEFT, ALIGN_RIGHT, ALIGN_CENTER, ALIGN_BLOCK<br /> <br /> === AddButton ===<br /> <br /> This call adds a push button object to the current group. The function supports the following keyword arguments:<br /> ; label<br /> : A string specifying the label to be displayed within the button. Defaults to an empty label.<br /> <br /> ; frame<br /> : One of the constants mentioned above for the group. Defaults to BUTTON_FRAME.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; onclick<br /> : A Python callable object that is invoked when the button is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id) where page_number is the page number of the GUI page and element_id is the element id returned by this call.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddCheckBox ===<br /> <br /> This call adds a checkbox object to the GUI. The following keyword arguments are valid:<br /> <br /> ; label<br /> : A string that appears as a label to the right of the checkbox. Defaults to an empty label.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; checked<br /> : An integer that specifies whether the checkbox is initially checked or not. A zero means the checkbox is clear, any other value says the box is checked.<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the checkbox is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, state) where page_number and element_id are the same as above, and state is a 0 if the user just unchecked the checkbox, or a 1 is it was just checked.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddRadioButton ===<br /> <br /> This call adds a set of mutually exclusive radio buttons. The following keyword arguments are valid:<br /> <br /> ; labels<br /> : A list of Python strings, with each of these strings appearing as a choice on the Radio buttons. This parameter is required.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; selected<br /> : The number of the button initially selected. Defaults to the first button (0).<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the radio button is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the button number that was selected.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddChooser ===<br /> <br /> This function adds a chooser gadget to the GUI. The following keyword arguments are valid:<br /> <br /> ; label<br /> : A test string to be displayed in the chooser in pop-up mode (see below). Defaults to an empty string, and is not used for drop-down mode.<br /> <br /> ; choices<br /> : A list of text strings to be displayed as choices for the chooser. This argument is mandatory.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; selected<br /> : The number of the currently visible item in drop-down mode. Defaults to 0.<br /> <br /> ; mode: One of the constants CHOOSER_POPUP or CHOOSER_DROPDOWN. This corresponds to the chooser.gadget CHOOSER_PopUp and CHOOSER_DropDown tag items.<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the chooser is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the title number that was selected.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddSpace ===<br /> <br /> This call adds a bit of space to the GUI. It accepts only one parameter:<br /> <br /> ; weight<br /> : An integer specifying the weight of the space. Defaults to 1.<br /> <br /> The call does not return a value. Space does not have any variables.<br /> <br /> == User Interface Settings ==<br /> <br /> In order to change some aspects of user interface elements (like the selection status of a checkbox) or read their current state, two functions exist called GetUIAttr and SetUIAttr.<br /> <br /> The former reads an attribute from an identified user interface element (identified by the page number and element id) while the latter sets (and updates the on-screen representation) of an equally identified element.<br /> <br /> A number of attributes can be set and gotten from UI elements; some of them are shared among more than one element type, while others are specific. The following list names the attributes:<br /> <br /> ; GUI_LABEL (string)<br /> : The label displayed on a UI element.<br /> : Applies to BUTTON, LABEL, GROUP, CHECKBOX<br /> <br /> ; GUI_SELECTED (integer)<br /> : The selected item in a chooser or radio button.<br /> : Applies to CHOOSER and RADIOBUTTON<br /> <br /> ; GUI_CHECKED (integer)<br /> : Whether the checkbox checkmark is set or not.<br /> : Applies to CHECKBOX<br /> <br /> ; GUI_ONCLICK (Python callable)<br /> : The handler invoked when the UI element is activated.<br /> : Applies to CHOOSER, BUTTON, LABEL, GROUP, CHECKBOX, RADIOBUTTON<br /> <br /> The GetUIAttr function's prototype looks like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> result = GetUIAttr(page_nr, id, attr)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> page_nr and id identify the object by giving the GUI's page number and the element id returned by the creation call. The attr parameter is one of the attributes given above. Valid parameters for attr are GUI_SELECTED, GUI_CHECKED and GUI_ONCLICK.<br /> <br /> For SetUIAttr, the prototype looks like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> SetUIAttr(page_nr, id, attr, value)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> page_nr and id and attr are the same as above. The value parameter specifies the new value of the attribute, and must match the type for the attribute or the call will have no effect.<br /> <br /> = Hints =<br /> <br /> * See the AmigaOS 4 installation script on the AmigaOS Installation CD. It is a big script full of functions. Take it as example and experiment.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=Installation_Utility&diff=7838 Installation Utility 2014-11-30T00:26:14Z <p>Philippe Ferrucci: /* AddPackage */</p> <hr /> <div>= How the installer works =<br /> <br /> == Basic concept ==<br /> <br /> The installation utility executes a python script that sets up the installation. In addition to standard Python commands the installation utility provides a module called &quot;installer&quot; and an interface to it. Using this interface you can create the different pages that can be found in almost all installation processes: a welcome page, a displayed licence page, a selection page, an installation page and finally a finish page.<br /> In the end, there are only a few script commands required.<br /> <br /> == Running an installation script ==<br /> <br /> === From the command line ===<br /> <br /> In order to run an installation from the command line, invoke the installation utility giving your script file as an argument and if you want a logo to be displayed at the top of the window:<br /> <br /> &lt;pre&gt;<br /> &quot;SYS:Utilities/Installation utility&quot; PACKAGE=myscript.py LOGO=mylogo.png<br /> &lt;/pre&gt;<br /> Note: the logo will be displayed all along the installation process.<br /> <br /> ''Note2: right now you need to set these argument names with capital letters, as shown above.''<br /> <br /> === From the Workbench ===<br /> <br /> Add a project icon to your script and use ''SYS:Utilities/Installation utility'' as the default tool.<br /> <br /> ==== Tooltypes ====<br /> <br /> * PACKAGE (Default: ''package.py'')<br /> <br /> This tooltype is used to specify the script name to execute. It is useful if you want to use a standalone icon that will open a script with a different name or in another directory.<br /> <br /> * LOGO<br /> <br /> You can use this tooltype to specify an image name to use in the installer window.<br /> <br /> = Example script =<br /> <br /> A minimal install script looks like this:<br /> <br /> &lt;pre&gt;<br /> # Simple, basic installation script<br /> from installer import *<br /> <br /> # These will be used for the first page (welcome) and last page (finish)<br /> welcomeText = &quot;This is a welcome text, displayed at the first page&quot;<br /> finishText = &quot;This is the finish message&quot;<br /> <br /> # Define the Welcome page<br /> welcomePage = NewPage(WELCOME)<br /> SetString(welcomePage, &quot;message&quot;, welcomeText)<br /> <br /> # Define the License page. The user must accept this license to continue the install process.<br /> # The license text will be read from a text file called &quot;license.txt&quot; and will be displayed on the page.<br /> licensePage = NewPage(LICENSE)<br /> <br /> # Define a page to select the installation directory<br /> destinationPage = NewPage(DESTINATION)<br /> SetString(destinationPage, &quot;message&quot;, &quot;Please indicate where you want to install the files .&quot;)<br /> SetString(destinationPage, &quot;destination&quot;, &quot;SYS:&quot;)<br /> <br /> # Define a directory to be copied to the destination<br /> filePack = AddPackage (FILEPACKAGE,<br /> name = &quot;Full directory&quot;,<br /> description = &quot;Directory to copy as-is in the destination&quot;,<br /> files = [&quot;data&quot;],<br /> optional = False<br /> )<br /> <br /> # Define a progress page that is shown during the installation<br /> installPage = NewPage(INSTALL)<br /> <br /> # Create a &quot;finish&quot; page.<br /> finalPage = NewPage(FINISH)<br /> SetString(finalPage, &quot;message&quot;, finishText)<br /> <br /> # Finally, this runs the installation.<br /> RunInstaller()<br /> &lt;/pre&gt;<br /> <br /> = Python Interface =<br /> <br /> == Introduction ==<br /> <br /> The installer is entirely programmed in Python. For this purpose, it provides a Python module called 'installer' that serves as a functional interface to the GUI. The entire GUI is build out of pages. Pages present different kind of information to the user. The installation can be navigated with a pair of forward/backward buttons to visit each page in turn. Certain pages (notably the INSTALL page) will trigger the installation process itself, although the interface is flexible enough to make an installation that is entirely driven by the Python script. A minimal setup function will create a &quot;default&quot; layout of pages for an installer. The basic is to have a single archive that is installed into a destination drawer created on the disk - about 90% of all installers will do exactly this. Therefore a lot of the mechanics involved in this type of installer is automated.<br /> <br /> == Python Functions in the installer package ==<br /> <br /> === NewPage ===<br /> <br /> This function creates a new page and returns its page number for later reference. The only argument to the function is the type of page to create. Possible values are:<br /> <br /> ; WELCOME<br /> : A message page, usually used for displaying a &quot;welcome&quot; message, although other uses are perfectly possible as well.<br /> : ''Note:'' this page is mandatory.<br /> <br /> ; FINISH<br /> : A message page that is specifically targeted at closing the installation. This page automatically gets the &quot;finish&quot; attribute set to make the installation change the &quot;cancel&quot; to the &quot;finish&quot; button.<br /> <br /> ; DESTINATION<br /> : A page to select a directory to serve as the target for the installation.<br /> : ''Note:'' this page is mandatory.<br /> <br /> ; INSTALL<br /> : The presence of this page automatically triggers the installation of the selected packages.<br /> <br /> ; GUI<br /> : A page where GUI elements can be added and controlled via a Python handler.<br /> <br /> ; PROCESSING<br /> : A page to display a simple progress bar for doing some Python-scripted processing.<br /> <br /> ; LICENSE<br /> : A brickwall page that displays a license agreement that only lets the user continue after accepting the license.<br /> : ''Note:'' the installation utility will look for a text file called &quot;license_''languagename''.language.txt&quot;, if not found, it will look for a file called &quot;license.txt&quot;.<br /> <br /> ; README<br /> : A page that displays a text file from disk for reference/README purposes.<br /> <br /> If the page cannot be generated, an OSError exception is raised.<br /> <br /> === GotoPage ===<br /> <br /> This function accepts a single argument, the page to display. This function should rarely be needed.<br /> <br /> === SetString, SetInteger, SetObject ===<br /> <br /> This function sets a variable of the specified type on a page. It accepts three parameters:<br /> * The Page number to set the variable on<br /> * The name of the variable<br /> * The variable content.<br /> <br /> === GetString, GetInteger, GetObject ===<br /> <br /> These functions are the reverse of the above - they read a variable from the page specified as its first argument and the name specified as the second argument. They return a default value if the name was not found.<br /> <br /> === RunInstaller ===<br /> <br /> This function runs the installer's main loop, and needs to be the last command in an installation. Any subsequent scripting is done via handlers connected to the pages.<br /> <br /> === AddPackage ===<br /> <br /> This function adds a package to the list of installable packages. The function's interface uses keywords to make it more readable. The keywords are:<br /> <br /> ; type<br /> : The type of package. This can be either FILEPACKAGE, ARCHIVEPACKAGE or HANDLERPACKAGE. A file package copies a list of files to the destination. An archive package unpacks a list of archives at the destination. Finally, a handler package is an abstract package that executes a handler when it is installed or upon certain actions.<br /> : This argument MUST be given.<br /> <br /> ; name<br /> : A string that specifies the name of the package. This name is presented to the user of the installer on a PACKAGESELECT page.<br /> : A name should be given. It defaults to an empty string.<br /> <br /> ; description<br /> : A textual description of the package. It is presented to the user next to the package list on a PACKAGESELECT page if the package is selected in the package list.<br /> : The description may be empty, although it is consider bad style. It defaults to an empty string.<br /> <br /> ; optional<br /> : A boolean value indicating whether the package is optional to install or required to be installed. A value of True means the package is optional.<br /> : Default is True (package is optional)<br /> <br /> ; selected<br /> : A boolean indicating whether the package should be pre-selected or not. If True, the package is selected the first time the PACKAGESELECT page is entered.<br /> : Default is True (package is selected), although the user might deselect the package on a PACKAGESELECT page<br /> <br /> ; diskspace<br /> : An integer value specifying the number of bytes the package occupies after installation. If a zero size is given (or the parameter is omitted) the installer tries to figure out the size requirements automatically, but be warned this might be a time consuming process.<br /> : Defaults to zero (try to figure out yourself)<br /> <br /> ; featuregroup<br /> : An integer bitmask giving one bit of each feature group defined. A one bit indicates this package is part of the group, while a zero bit indicates it isn't.<br /> : Defaults to zero (not in any feature group)<br /> <br /> ; alternatepath<br /> : Specifies an alternative installation path. For example, some files might need to be installed into LIBS: instead of the usual destination. This feature should be used with care.<br /> : Defaults to None (i.e. no alternate path)<br /> <br /> ; files<br /> : A list of strings, each string representing one file associated with this package. The interpretation of these files depend on the package type:<br /> :: ARCHIVEPACKAGE: each file is an archive that is supposed to be extracted into the destination.<br /> :: HANDLERPACKAGE: The strings are not interpreted in any way, it is up to the handler to do that.<br /> :: FILEPACKAGE: Each string stands for a file or directory to be copied. Files are straight copies, while directory names are interpreted slightly different: if a directory name is given, that entire directory is copied to the destination, including the directory itself. For example, if you specify &quot;System&quot; then the destination directory will include a &quot;System&quot; directory. On the other hand, if you specify it as &quot;System/&quot; with a trailing slash, the content of the directory will be copied but not the directory itself, i.e. the destination directory would contain all the file and directories in the &quot;System&quot; directory but not the directory itself.<br /> :: ''Note:'' directory/file names must be relative to the current directory i.e. where the installer is executed. You cannot use here a complete path name with the volume name like ''RAM:mydir''.<br /> : The default is an empty list.<br /> <br /> The result of this function is a package number, which can be used subsequently to adjust package settings or query certain features.<br /> <br /> == GUI's ==<br /> <br /> GUI's must be created from scratch using a procedural interface. The following procedures deal with creating and handling the user interface. In general, the user interface must be generated once and cannot be changed afterwards (with exceptions, see below).<br /> <br /> A GUI is started with a call to StartGUI(page_number). This will start to create a GUI on the indicated page number, and all subsequent calls will add to this GUI until EndGUI() is called. If the indicated page number is invalid or is not a GUI page, ever subsequent calls are ignored until a new StartGUI with a valid page number is called.<br /> <br /> Immediately after the call, a single GUI object might be defined. In almost all cases, this will be a group to hold a number of GUI elements. Groups are defined with the BeginGroup and EndGroup calls.<br /> <br /> BeginGroup takes the following keyword arguments:<br /> ; orientation<br /> : This specifies whether the children of this group are laid out vertically or horizontally. By default the layout is vertically.<br /> ; label<br /> : A short text string that can be displayed as a label for this group. The label is only used if a frame other than NONE_FRAME is specified. By default no label is used.<br /> ; frame<br /> : One of the constants NONE_FRAME, THIN_FRAME, BUTTON_FRAME, GROUP_FRAME, FIELD_FRAME, DROPBOX_FRAME, SBAR_HORIZ_FRAME, SBAR_VERT_FRAME, BOX_FRAME, STANDARD_FRAME. They directly correspond to the bevel styles of bevel.image. Defaults to NONE_FRAME.<br /> ; weight<br /> : An integer defining the weighted width or height of this group. This corresponds to layout.gadget's CHILD_WeightedWidth or CHILD_WeightedHeight tags, depending on the layout direction.<br /> <br /> EndGroup has no parameters and automatically terminates the last group opened by BeginGroup.<br /> <br /> User interface elements are added with the following calls. All of these return an ID number.<br /> <br /> === AddLabel ===<br /> <br /> This call adds a text label, with selectable frame. The following keyword arguments are supported:<br /> ; label<br /> : A string that specifies the label to be displayed. Default is empty, although an empty label doesn't make much sense<br /> <br /> ; frame<br /> : A frame to put around the label.<br /> <br /> ; weight<br /> : The weight of the label, as explained above.<br /> <br /> ; align<br /> : Text alignment to use for the label<br /> <br /> === AddButton ===<br /> <br /> This call adds a push button object to the current group. The function supports the following keyword arguments:<br /> ; label<br /> : A string specifying the label to be displayed within the button. Defaults to an empty label.<br /> <br /> ; frame<br /> : One of the constants mentioned above for the group. Defaults to BUTTON_FRAME.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; onclick<br /> : A Python callable object that is invoked when the button is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id) where page_number is the page number of the GUI page and element_id is the element id returned by this call.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddCheckBox ===<br /> <br /> This call adds a checkbox object to the GUI. The following keyword arguments are valid:<br /> <br /> ; label<br /> : A string that appears as a label to the right of the checkbox. Defaults to an empty label.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; checked<br /> : An integer that specifies whether the checkbox is initially checked or not. A zero means the checkbox is clear, any other value says the box is checked.<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the checkbox is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, state) where page_number and element_id are the same as above, and state is a 0 if the user just unchecked the checkbox, or a 1 is it was just checked.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddRadioButton ===<br /> <br /> This call adds a set of mutually exclusive radio buttons. The following keyword arguments are valid:<br /> <br /> ; labels<br /> : A list of Python strings, with each of these strings appearing as a choice on the Radio buttons. This parameter is required.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; selected<br /> : The number of the button initially selected. Defaults to the first button (0).<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the radio button is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the button number that was selected.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddChooser ===<br /> <br /> This function adds a chooser gadget to the GUI. The following keyword arguments are valid:<br /> <br /> ; label<br /> : A test string to be displayed in the chooser in pop-up mode (see below). Defaults to an empty string, and is not used for drop-down mode.<br /> <br /> ; choices<br /> : A list of text strings to be displayed as choices for the chooser. This argument is mandatory.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; selected<br /> : The number of the currently visible item in drop-down mode. Defaults to 0.<br /> <br /> ; mode: One of the constants CHOOSER_POPUP or CHOOSER_DROPDOWN. This corresponds to the chooser.gadget CHOOSER_PopUp and CHOOSER_DropDown tag items.<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the chooser is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the title number that was selected.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddSpace ===<br /> <br /> This call adds a bit of space to the GUI. It accepts only one parameter:<br /> <br /> ; weight<br /> : An integer specifying the weight of the space. Defaults to 1.<br /> <br /> The call does not return a value. Space does not have any variables.<br /> <br /> == User Interface Settings ==<br /> <br /> In order to change some aspects of user interface elements (like the selection status of a checkbox) or read their current state, two functions exist called GetUIAttr and SetUIAttr.<br /> <br /> The former reads an attribute from an identified user interface element (identified by the page number and element id) while the latter sets (and updates the on-screen representation) of an equally identified element.<br /> <br /> A number of attributes can be set and gotten from UI elements; some of them are shared among more than one element type, while others are specific. The following list names the attributes:<br /> <br /> ; GUI_LABEL (string)<br /> : The label displayed on a UI element.<br /> : Applies to BUTTON, LABEL, GROUP, CHECKBOX<br /> <br /> ; GUI_SELECTED (integer)<br /> : The selected item in a chooser or radio button.<br /> : Applies to CHOOSER and RADIOBUTTON<br /> <br /> ; GUI_CHECKED (integer)<br /> : Whether the checkbox checkmark is set or not.<br /> : Applies to CHECKBOX<br /> <br /> ; GUI_ONCLICK (Python callable)<br /> : The handler invoked when the UI element is activated.<br /> : Applies to CHOOSER, BUTTON, LABEL, GROUP, CHECKBOX, RADIOBUTTON<br /> <br /> The GetUIAttr function's prototype looks like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> result = GetUIAttr(page_nr, id, attr)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> page_nr and id identify the object by giving the GUI's page number and the element id returned by the creation call. The attr parameter is one of the attributes given above. Valid parameters for attr are GUI_SELECTED, GUI_CHECKED and GUI_ONCLICK.<br /> <br /> For SetUIAttr, the prototype looks like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> SetUIAttr(page_nr, id, attr, value)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> page_nr and id and attr are the same as above. The value parameter specifies the new value of the attribute, and must match the type for the attribute or the call will have no effect.<br /> <br /> = Hints =<br /> <br /> * See the AmigaOS 4 installation script on the AmigaOS Installation CD. It is a big script full of functions. Take it as example and experiment.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=Installation_Utility&diff=7837 Installation Utility 2014-11-30T00:23:13Z <p>Philippe Ferrucci: /* AddLabel */</p> <hr /> <div>= How the installer works =<br /> <br /> == Basic concept ==<br /> <br /> The installation utility executes a python script that sets up the installation. In addition to standard Python commands the installation utility provides a module called &quot;installer&quot; and an interface to it. Using this interface you can create the different pages that can be found in almost all installation processes: a welcome page, a displayed licence page, a selection page, an installation page and finally a finish page.<br /> In the end, there are only a few script commands required.<br /> <br /> == Running an installation script ==<br /> <br /> === From the command line ===<br /> <br /> In order to run an installation from the command line, invoke the installation utility giving your script file as an argument and if you want a logo to be displayed at the top of the window:<br /> <br /> &lt;pre&gt;<br /> &quot;SYS:Utilities/Installation utility&quot; PACKAGE=myscript.py LOGO=mylogo.png<br /> &lt;/pre&gt;<br /> Note: the logo will be displayed all along the installation process.<br /> <br /> ''Note2: right now you need to set these argument names with capital letters, as shown above.''<br /> <br /> === From the Workbench ===<br /> <br /> Add a project icon to your script and use ''SYS:Utilities/Installation utility'' as the default tool.<br /> <br /> ==== Tooltypes ====<br /> <br /> * PACKAGE (Default: ''package.py'')<br /> <br /> This tooltype is used to specify the script name to execute. It is useful if you want to use a standalone icon that will open a script with a different name or in another directory.<br /> <br /> * LOGO<br /> <br /> You can use this tooltype to specify an image name to use in the installer window.<br /> <br /> = Example script =<br /> <br /> A minimal install script looks like this:<br /> <br /> &lt;pre&gt;<br /> # Simple, basic installation script<br /> from installer import *<br /> <br /> # These will be used for the first page (welcome) and last page (finish)<br /> welcomeText = &quot;This is a welcome text, displayed at the first page&quot;<br /> finishText = &quot;This is the finish message&quot;<br /> <br /> # Define the Welcome page<br /> welcomePage = NewPage(WELCOME)<br /> SetString(welcomePage, &quot;message&quot;, welcomeText)<br /> <br /> # Define the License page. The user must accept this license to continue the install process.<br /> # The license text will be read from a text file called &quot;license.txt&quot; and will be displayed on the page.<br /> licensePage = NewPage(LICENSE)<br /> <br /> # Define a page to select the installation directory<br /> destinationPage = NewPage(DESTINATION)<br /> SetString(destinationPage, &quot;message&quot;, &quot;Please indicate where you want to install the files .&quot;)<br /> SetString(destinationPage, &quot;destination&quot;, &quot;SYS:&quot;)<br /> <br /> # Define a directory to be copied to the destination<br /> filePack = AddPackage (FILEPACKAGE,<br /> name = &quot;Full directory&quot;,<br /> description = &quot;Directory to copy as-is in the destination&quot;,<br /> files = [&quot;data&quot;],<br /> optional = False<br /> )<br /> <br /> # Define a progress page that is shown during the installation<br /> installPage = NewPage(INSTALL)<br /> <br /> # Create a &quot;finish&quot; page.<br /> finalPage = NewPage(FINISH)<br /> SetString(finalPage, &quot;message&quot;, finishText)<br /> <br /> # Finally, this runs the installation.<br /> RunInstaller()<br /> &lt;/pre&gt;<br /> <br /> = Python Interface =<br /> <br /> == Introduction ==<br /> <br /> The installer is entirely programmed in Python. For this purpose, it provides a Python module called 'installer' that serves as a functional interface to the GUI. The entire GUI is build out of pages. Pages present different kind of information to the user. The installation can be navigated with a pair of forward/backward buttons to visit each page in turn. Certain pages (notably the INSTALL page) will trigger the installation process itself, although the interface is flexible enough to make an installation that is entirely driven by the Python script. A minimal setup function will create a &quot;default&quot; layout of pages for an installer. The basic is to have a single archive that is installed into a destination drawer created on the disk - about 90% of all installers will do exactly this. Therefore a lot of the mechanics involved in this type of installer is automated.<br /> <br /> == Python Functions in the installer package ==<br /> <br /> === NewPage ===<br /> <br /> This function creates a new page and returns its page number for later reference. The only argument to the function is the type of page to create. Possible values are:<br /> <br /> ; WELCOME<br /> : A message page, usually used for displaying a &quot;welcome&quot; message, although other uses are perfectly possible as well.<br /> : ''Note:'' this page is mandatory.<br /> <br /> ; FINISH<br /> : A message page that is specifically targeted at closing the installation. This page automatically gets the &quot;finish&quot; attribute set to make the installation change the &quot;cancel&quot; to the &quot;finish&quot; button.<br /> <br /> ; DESTINATION<br /> : A page to select a directory to serve as the target for the installation.<br /> : ''Note:'' this page is mandatory.<br /> <br /> ; INSTALL<br /> : The presence of this page automatically triggers the installation of the selected packages.<br /> <br /> ; GUI<br /> : A page where GUI elements can be added and controlled via a Python handler.<br /> <br /> ; PROCESSING<br /> : A page to display a simple progress bar for doing some Python-scripted processing.<br /> <br /> ; LICENSE<br /> : A brickwall page that displays a license agreement that only lets the user continue after accepting the license.<br /> : ''Note:'' the installation utility will look for a text file called &quot;license_''languagename''.language.txt&quot;, if not found, it will look for a file called &quot;license.txt&quot;.<br /> <br /> ; README<br /> : A page that displays a text file from disk for reference/README purposes.<br /> <br /> If the page cannot be generated, an OSError exception is raised.<br /> <br /> === GotoPage ===<br /> <br /> This function accepts a single argument, the page to display. This function should rarely be needed.<br /> <br /> === SetString, SetInteger, SetObject ===<br /> <br /> This function sets a variable of the specified type on a page. It accepts three parameters:<br /> * The Page number to set the variable on<br /> * The name of the variable<br /> * The variable content.<br /> <br /> === GetString, GetInteger, GetObject ===<br /> <br /> These functions are the reverse of the above - they read a variable from the page specified as its first argument and the name specified as the second argument. They return a default value if the name was not found.<br /> <br /> === RunInstaller ===<br /> <br /> This function runs the installer's main loop, and needs to be the last command in an installation. Any subsequent scripting is done via handlers connected to the pages.<br /> <br /> === AddPackage ===<br /> <br /> This function adds a package to the list of installable packages. The function's interface uses keywords to make it more readable. The keywords are<br /> <br /> ; type<br /> : The type of package. This can be either FILEPACKAGE, ARCHIVEPACKAGE or HANDLERPACKAGE. A file package copies a list of files to the destination. An archive package unpacks a list of archives at the destination. Finally, a handler package is an abstract package that executes a handler when it is installed or upon certain actions.<br /> : This argument MUST be given.<br /> <br /> ; name<br /> : A string that specifies the name of the package. This name is presented to the user of the installer on a PACKAGESELECT page.<br /> : A name should be given. It defaults to an empty string.<br /> <br /> ; description<br /> : A textual description of the package. It is presented to the user next to the package list on a PACKAGESELECT page if the package is selected in the package list.<br /> : The description may be empty, although it is consider bad style. It defaults to an empty string.<br /> <br /> ; optional<br /> : A boolean value indicating whether the package is optional to install or required to be installed. A value of True means the package is optional.<br /> : Default is True (package is optional)<br /> <br /> ; selected<br /> : A boolean indicating whether the package should be pre-selected or not. If True, the package is selected the first time the PACKAGESELECT page is entered.<br /> : Default is True (package is selected), although the user might deselect the package on a PACKAGESELECT page<br /> <br /> ; diskspace<br /> : An integer value specifying the number of bytes the package occupies after installation. If a zero size is given (or the parameter is omitted) the installer tries to figure out the size requirements automatically, but be warned this might be a time consuming process.<br /> : Defaults to zero (try to figure out yourself)<br /> <br /> ; featuregroup<br /> : An integer bitmask giving one bit of each feature group defined. A one bit indicates this package is part of the group, while a zero bit indicates it isn't.<br /> : Defaults to zero (not in any feature group)<br /> <br /> ; alternatepath<br /> : Specifies an alternative installation path. For example, some files might need to be installed into LIBS: instead of the usual destination. This feature should be used with care.<br /> : Defaults to None (i.e. no alternate path)<br /> <br /> ; files<br /> : A list of strings, each string representing one file associated with this package. The interpretation of these files depend on the package type:<br /> :: ARCHIVEPACKAGE: each file is an archive that is supposed to be extracted into the destination.<br /> :: HANDLERPACKAGE: The strings are not interpreted in any way, it is up to the handler to do that.<br /> :: FILEPACKAGE: Each string stands for a file or directory to be copied. Files are straight copies, while directory names are interpreted slightly different: if a directory name is given, that entire directory is copied to the destination, including the directory itself. For example, if you specify &quot;System&quot; then the destination directory will include a &quot;System&quot; directory. On the other hand, if you specify it as &quot;System/&quot; with a trailing slash, the content of the directory will be copied but not the directory itself, i.e. the destination directory would contain all the file and directories in the &quot;System&quot; directory but not the directory itself.<br /> :: ''Note:'' directory/file names must be relative to the current directory i.e. where the installer is executed. You cannot use here a complete path name with the volume name like ''RAM:mydir''.<br /> : The default is an empty list.<br /> <br /> The result of this function is a package number, which can be used subsequently to adjust package settings or query certain features.<br /> <br /> == GUI's ==<br /> <br /> GUI's must be created from scratch using a procedural interface. The following procedures deal with creating and handling the user interface. In general, the user interface must be generated once and cannot be changed afterwards (with exceptions, see below).<br /> <br /> A GUI is started with a call to StartGUI(page_number). This will start to create a GUI on the indicated page number, and all subsequent calls will add to this GUI until EndGUI() is called. If the indicated page number is invalid or is not a GUI page, ever subsequent calls are ignored until a new StartGUI with a valid page number is called.<br /> <br /> Immediately after the call, a single GUI object might be defined. In almost all cases, this will be a group to hold a number of GUI elements. Groups are defined with the BeginGroup and EndGroup calls.<br /> <br /> BeginGroup takes the following keyword arguments:<br /> ; orientation<br /> : This specifies whether the children of this group are laid out vertically or horizontally. By default the layout is vertically.<br /> ; label<br /> : A short text string that can be displayed as a label for this group. The label is only used if a frame other than NONE_FRAME is specified. By default no label is used.<br /> ; frame<br /> : One of the constants NONE_FRAME, THIN_FRAME, BUTTON_FRAME, GROUP_FRAME, FIELD_FRAME, DROPBOX_FRAME, SBAR_HORIZ_FRAME, SBAR_VERT_FRAME, BOX_FRAME, STANDARD_FRAME. They directly correspond to the bevel styles of bevel.image. Defaults to NONE_FRAME.<br /> ; weight<br /> : An integer defining the weighted width or height of this group. This corresponds to layout.gadget's CHILD_WeightedWidth or CHILD_WeightedHeight tags, depending on the layout direction.<br /> <br /> EndGroup has no parameters and automatically terminates the last group opened by BeginGroup.<br /> <br /> User interface elements are added with the following calls. All of these return an ID number.<br /> <br /> === AddLabel ===<br /> <br /> This call adds a text label, with selectable frame. The following keyword arguments are supported:<br /> ; label<br /> : A string that specifies the label to be displayed. Default is empty, although an empty label doesn't make much sense<br /> <br /> ; frame<br /> : A frame to put around the label.<br /> <br /> ; weight<br /> : The weight of the label, as explained above.<br /> <br /> ; align<br /> : Text alignment to use for the label<br /> <br /> === AddButton ===<br /> <br /> This call adds a push button object to the current group. The function supports the following keyword arguments:<br /> ; label<br /> : A string specifying the label to be displayed within the button. Defaults to an empty label.<br /> <br /> ; frame<br /> : One of the constants mentioned above for the group. Defaults to BUTTON_FRAME.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; onclick<br /> : A Python callable object that is invoked when the button is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id) where page_number is the page number of the GUI page and element_id is the element id returned by this call.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddCheckBox ===<br /> <br /> This call adds a checkbox object to the GUI. The following keyword arguments are valid:<br /> <br /> ; label<br /> : A string that appears as a label to the right of the checkbox. Defaults to an empty label.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; checked<br /> : An integer that specifies whether the checkbox is initially checked or not. A zero means the checkbox is clear, any other value says the box is checked.<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the checkbox is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, state) where page_number and element_id are the same as above, and state is a 0 if the user just unchecked the checkbox, or a 1 is it was just checked.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddRadioButton ===<br /> <br /> This call adds a set of mutually exclusive radio buttons. The following keyword arguments are valid:<br /> <br /> ; labels<br /> : A list of Python strings, with each of these strings appearing as a choice on the Radio buttons. This parameter is required.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; selected<br /> : The number of the button initially selected. Defaults to the first button (0).<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the radio button is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the button number that was selected.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddChooser ===<br /> <br /> This function adds a chooser gadget to the GUI. The following keyword arguments are valid:<br /> <br /> ; label<br /> : A test string to be displayed in the chooser in pop-up mode (see below). Defaults to an empty string, and is not used for drop-down mode.<br /> <br /> ; choices<br /> : A list of text strings to be displayed as choices for the chooser. This argument is mandatory.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; selected<br /> : The number of the currently visible item in drop-down mode. Defaults to 0.<br /> <br /> ; mode: One of the constants CHOOSER_POPUP or CHOOSER_DROPDOWN. This corresponds to the chooser.gadget CHOOSER_PopUp and CHOOSER_DropDown tag items.<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the chooser is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the title number that was selected.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddSpace ===<br /> <br /> This call adds a bit of space to the GUI. It accepts only one parameter:<br /> <br /> ; weight<br /> : An integer specifying the weight of the space. Defaults to 1.<br /> <br /> The call does not return a value. Space does not have any variables.<br /> <br /> == User Interface Settings ==<br /> <br /> In order to change some aspects of user interface elements (like the selection status of a checkbox) or read their current state, two functions exist called GetUIAttr and SetUIAttr.<br /> <br /> The former reads an attribute from an identified user interface element (identified by the page number and element id) while the latter sets (and updates the on-screen representation) of an equally identified element.<br /> <br /> A number of attributes can be set and gotten from UI elements; some of them are shared among more than one element type, while others are specific. The following list names the attributes:<br /> <br /> ; GUI_LABEL (string)<br /> : The label displayed on a UI element.<br /> : Applies to BUTTON, LABEL, GROUP, CHECKBOX<br /> <br /> ; GUI_SELECTED (integer)<br /> : The selected item in a chooser or radio button.<br /> : Applies to CHOOSER and RADIOBUTTON<br /> <br /> ; GUI_CHECKED (integer)<br /> : Whether the checkbox checkmark is set or not.<br /> : Applies to CHECKBOX<br /> <br /> ; GUI_ONCLICK (Python callable)<br /> : The handler invoked when the UI element is activated.<br /> : Applies to CHOOSER, BUTTON, LABEL, GROUP, CHECKBOX, RADIOBUTTON<br /> <br /> The GetUIAttr function's prototype looks like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> result = GetUIAttr(page_nr, id, attr)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> page_nr and id identify the object by giving the GUI's page number and the element id returned by the creation call. The attr parameter is one of the attributes given above. Valid parameters for attr are GUI_SELECTED, GUI_CHECKED and GUI_ONCLICK.<br /> <br /> For SetUIAttr, the prototype looks like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> SetUIAttr(page_nr, id, attr, value)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> page_nr and id and attr are the same as above. The value parameter specifies the new value of the attribute, and must match the type for the attribute or the call will have no effect.<br /> <br /> = Hints =<br /> <br /> * See the AmigaOS 4 installation script on the AmigaOS Installation CD. It is a big script full of functions. Take it as example and experiment.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=MultiView&diff=7669 MultiView 2014-05-05T16:01:40Z <p>Philippe Ferrucci: /* Command line examples */</p> <hr /> <div>= Introduction =<br /> <br /> Multiview can read any file for which there is a descriptor file in Devs:Datatypes. These tell Multiview (and any other programs written to take advantage of datatypes) how to load the various types of files.<br /> <br /> = Command line arguments =<br /> <br /> ; FILE<br /> : Name of the file you want to be displayed/played by Multiview. Alternatively you can specify a volume or directory name that will be used by Multiview as the current directory when it opens its requester.<br /> : Note: this argument is optional as Multiview can be used to display the content of a clipboard unit instead of a file.<br /> <br /> ; CLIPBOARD/S<br /> : Argument that will make Multiview display the content of the clipboard unit specified with the CLIPUNIT argument.<br /> <br /> ; CLIPUNIT/K/N<br /> : Clipboard unit you want to display with Multiview. Default is 0.<br /> <br /> ; SCREEN/S<br /> : Arguments that will make Multiview open its view window on its own screen.<br /> <br /> ; PUBSCREEN/K<br /> : Name of a public screen you want Multiview to open its window on.<br /> : Note: usage of the SCREEN switch is implicit so it is not needed. If you quit the program which is owner of the public screen while Multiview is still opened the application will probably crash as it is not necessarily aware of an alien windows opened on its screen.<br /> <br /> ; REQUESTER/S<br /> <br /> ; BOOKMARK/S<br /> : Reads file ENV:MultiView.bookmark<br /> <br /> ; FONTNAME/K<br /> : Name of the font Multiview will use to display text and AmigaGuide files. If none is specified here Multiview will use the default system font.<br /> <br /> ; FONTSIZE/K/N<br /> : Size of the font Multiview will use to display text and AmigaGuide files. If none is specified here Multiview will use the default system font.<br /> <br /> ; CHARSET/K<br /> : Charset to use to display text and AmigaGuide files.<br /> <br /> ; BACKDROP/S<br /> : When this argument is used Multiview will open its display window in backdrop mode.<br /> <br /> ; WINDOW/S<br /> : By default when running Multiview with no arguments, it will open a requester the user can use to select a file to load. With the WINDOW switch Multiview will open with a blank window and no loaded file. The user will have to select Open in the Project menu to select a file to load in Multiview.<br /> <br /> ; PORTNAME/K<br /> : Name of the AREXX port to create. By default the port name is MULTIVIEW.n with &quot;n&quot; being an incremental number starting from 1. It is incremented for each started Multiview instance.<br /> <br /> ; IMMEDIATE/S<br /> : Indicate whether the object should immediately begin playing. Defaults to FALSE.<br /> <br /> ; REPEAT/S<br /> : Indicate that the object should repeat playing. Defaults to FALSE.<br /> <br /> ; PRTUNIT/K/N<br /> : Printer unit to use when printing on &quot;printer.device&quot;. Defaults to 0.<br /> <br /> ; WINDOWLEFT/K/N,WINDOWTOP/K/N,WINDOWWIDTH/K/N,WINDOWHEIGHT/K/N<br /> : WINDOWLEFT is the number of pixels the Multiview window should open from the left screen border. Defaults to 0.<br /> : WINDOWTOP is the number of pixels the Multiview window should open from the top screen border. Defaults to screen titlebar height so that Multiview window opens right below the titlebar.<br /> : WINDOWWIDTH is the number of pixels wide the Multiview window should be. Defaults to the screen width.<br /> : WINDOWHEIGHT is the number of pixels height the Multiview window should be. Defaults to the screen height.<br /> <br /> ; AUTORESIZE/S<br /> <br /> = Command line examples =<br /> <br /> Multiview S:Startup-sequence screen windowleft 50 windowtop 90 windowwidth 200 windowheight 200<br /> <br /> Displays the file S:Startup-sequence in a window which has the size of 200x200 opened at 50 pixels from the left of the screen and at 90 pixels from the top of the screen. The window is opened on its own screen.<br /> <br /> = ARexx Commands =<br /> <br /> OPEN<br /> <br /> NAME/K,CLIPBOARD/S,CLIPUNIT/K/N<br /> Open a file, or the contents of the specified clipboard unit.<br /> <br /> RELOAD<br /> Reload the current object.<br /> <br /> SAVEAS<br /> <br /> NAME/K,IFF/S<br /> Save the current object to disk. The IFF switch is used to force the<br /> save to be IFF instead of RAW (local format).<br /> <br /> PRINT<br /> Print the current object.<br /> <br /> ABOUT<br /> Display a requester with information about the current object.<br /> <br /> QUIT<br /> Quit MultiView.<br /> <br /> MARK<br /> Start Mark mode.<br /> <br /> COPY<br /> Copy the currently selected block (or the whole object if no<br /> selected block exists) to the clipboard.<br /> <br /> PASTE<br /> <br /> UNIT/N<br /> Open the contents of the specified clipboard unit. PASTE &lt;n&gt; is a<br /> shortcut for OPEN CLIPBOARD CLIPUNIT &lt;n&gt;.<br /> <br /> CLEARSELECTED<br /> Deselect the currently selected block, if one exists.<br /> <br /> GETTRIGGERINFO<br /> <br /> VAR/S,STEM/K<br /> Provide a list of trigger methods that the current object supports.<br /> <br /> VAR causes the information to be returned in RESULT.<br /> <br /> STEM causes the information to be returned in the named stem variable.<br /> The following values are supported:<br /> <br /> stem.count number of elements in the array.<br /> stem.n.label label<br /> stem.n.command command<br /> stem.n.method method<br /> <br /> DOTRIGGERMETHOD<br /> <br /> METHOD/A<br /> Perform a trigger method on the current object.<br /> <br /> SCREEN<br /> <br /> TRUE/S,FALSE/S<br /> Cause the object to be displayed on an own screen or not.<br /> <br /> PUBSCREEN<br /> <br /> NAME/A<br /> Cause the object to be displayed on the specified public screen.<br /> <br /> SNAPSHOT<br /> Save the current window position to ENVARC:MultiView/&lt;screen name&gt;.<br /> <br /> GETCURRENTDIR<br /> Return the current directory for the current object.<br /> <br /> GETFILEINFO<br /> Get the file information for the current object.<br /> <br /> GETOBJECTINFO<br /> <br /> VAR/S,STEM/K<br /> Return information about the current object.<br /> <br /> VAR causes the information to be returned in RESULT.<br /> <br /> &quot;name&quot;,&quot;basename&quot;,&quot;group&quot;,&quot;id&quot;<br /> <br /> STEM causes the information to be returned in the named stem variable.<br /> <br /> stem.filename file name of the current object.<br /> stem.name object type name.<br /> stem.basename object type basename.<br /> stem.group object type group.<br /> stem.id object type id.<br /> <br /> MINIMUMSIZE<br /> Resize the object's window to its minimum size.<br /> <br /> NORMALSIZE<br /> Resize the object's window to its nominal size.<br /> <br /> MAXIMUMSIZE<br /> Resize the object's window to its maximum size.<br /> <br /> WINDOWTOFRONT<br /> Bring the object's window to front.<br /> <br /> WINDOWTOBACK<br /> Send the object's window to back.<br /> <br /> ACTIVATEWINDOW<br /> Activate the object's window.<br /> <br /> SCREENTOFRONT<br /> Bring the object's screen to front.<br /> <br /> SCREENTOBACK<br /> Send the object's screen to back.<br /> <br /> BEEPSCREEN<br /> Cause a display beep on the object's screen.<br /> <br /> NEXT<br /> <br /> ''Note: only when viewing an Amigaguide file.''<br /> <br /> Jumps to the next node in the guide.<br /> <br /> PREVIOUS<br /> <br /> Note: only when viewing an Amigaguide file.<br /> <br /> Jumps to the previous node in the guide.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=MultiView&diff=7668 MultiView 2014-05-05T15:59:02Z <p>Philippe Ferrucci: /* Command line arguments */</p> <hr /> <div>= Introduction =<br /> <br /> Multiview can read any file for which there is a descriptor file in Devs:Datatypes. These tell Multiview (and any other programs written to take advantage of datatypes) how to load the various types of files.<br /> <br /> = Command line arguments =<br /> <br /> ; FILE<br /> : Name of the file you want to be displayed/played by Multiview. Alternatively you can specify a volume or directory name that will be used by Multiview as the current directory when it opens its requester.<br /> : Note: this argument is optional as Multiview can be used to display the content of a clipboard unit instead of a file.<br /> <br /> ; CLIPBOARD/S<br /> : Argument that will make Multiview display the content of the clipboard unit specified with the CLIPUNIT argument.<br /> <br /> ; CLIPUNIT/K/N<br /> : Clipboard unit you want to display with Multiview. Default is 0.<br /> <br /> ; SCREEN/S<br /> : Arguments that will make Multiview open its view window on its own screen.<br /> <br /> ; PUBSCREEN/K<br /> : Name of a public screen you want Multiview to open its window on.<br /> : Note: usage of the SCREEN switch is implicit so it is not needed. If you quit the program which is owner of the public screen while Multiview is still opened the application will probably crash as it is not necessarily aware of an alien windows opened on its screen.<br /> <br /> ; REQUESTER/S<br /> <br /> ; BOOKMARK/S<br /> : Reads file ENV:MultiView.bookmark<br /> <br /> ; FONTNAME/K<br /> : Name of the font Multiview will use to display text and AmigaGuide files. If none is specified here Multiview will use the default system font.<br /> <br /> ; FONTSIZE/K/N<br /> : Size of the font Multiview will use to display text and AmigaGuide files. If none is specified here Multiview will use the default system font.<br /> <br /> ; CHARSET/K<br /> : Charset to use to display text and AmigaGuide files.<br /> <br /> ; BACKDROP/S<br /> : When this argument is used Multiview will open its display window in backdrop mode.<br /> <br /> ; WINDOW/S<br /> : By default when running Multiview with no arguments, it will open a requester the user can use to select a file to load. With the WINDOW switch Multiview will open with a blank window and no loaded file. The user will have to select Open in the Project menu to select a file to load in Multiview.<br /> <br /> ; PORTNAME/K<br /> : Name of the AREXX port to create. By default the port name is MULTIVIEW.n with &quot;n&quot; being an incremental number starting from 1. It is incremented for each started Multiview instance.<br /> <br /> ; IMMEDIATE/S<br /> : Indicate whether the object should immediately begin playing. Defaults to FALSE.<br /> <br /> ; REPEAT/S<br /> : Indicate that the object should repeat playing. Defaults to FALSE.<br /> <br /> ; PRTUNIT/K/N<br /> : Printer unit to use when printing on &quot;printer.device&quot;. Defaults to 0.<br /> <br /> ; WINDOWLEFT/K/N,WINDOWTOP/K/N,WINDOWWIDTH/K/N,WINDOWHEIGHT/K/N<br /> : WINDOWLEFT is the number of pixels the Multiview window should open from the left screen border. Defaults to 0.<br /> : WINDOWTOP is the number of pixels the Multiview window should open from the top screen border. Defaults to screen titlebar height so that Multiview window opens right below the titlebar.<br /> : WINDOWWIDTH is the number of pixels wide the Multiview window should be. Defaults to the screen width.<br /> : WINDOWHEIGHT is the number of pixels height the Multiview window should be. Defaults to the screen height.<br /> <br /> ; AUTORESIZE/S<br /> <br /> = Command line examples =<br /> <br /> Multiview...<br /> <br /> = ARexx Commands =<br /> <br /> OPEN<br /> <br /> NAME/K,CLIPBOARD/S,CLIPUNIT/K/N<br /> Open a file, or the contents of the specified clipboard unit.<br /> <br /> RELOAD<br /> Reload the current object.<br /> <br /> SAVEAS<br /> <br /> NAME/K,IFF/S<br /> Save the current object to disk. The IFF switch is used to force the<br /> save to be IFF instead of RAW (local format).<br /> <br /> PRINT<br /> Print the current object.<br /> <br /> ABOUT<br /> Display a requester with information about the current object.<br /> <br /> QUIT<br /> Quit MultiView.<br /> <br /> MARK<br /> Start Mark mode.<br /> <br /> COPY<br /> Copy the currently selected block (or the whole object if no<br /> selected block exists) to the clipboard.<br /> <br /> PASTE<br /> <br /> UNIT/N<br /> Open the contents of the specified clipboard unit. PASTE &lt;n&gt; is a<br /> shortcut for OPEN CLIPBOARD CLIPUNIT &lt;n&gt;.<br /> <br /> CLEARSELECTED<br /> Deselect the currently selected block, if one exists.<br /> <br /> GETTRIGGERINFO<br /> <br /> VAR/S,STEM/K<br /> Provide a list of trigger methods that the current object supports.<br /> <br /> VAR causes the information to be returned in RESULT.<br /> <br /> STEM causes the information to be returned in the named stem variable.<br /> The following values are supported:<br /> <br /> stem.count number of elements in the array.<br /> stem.n.label label<br /> stem.n.command command<br /> stem.n.method method<br /> <br /> DOTRIGGERMETHOD<br /> <br /> METHOD/A<br /> Perform a trigger method on the current object.<br /> <br /> SCREEN<br /> <br /> TRUE/S,FALSE/S<br /> Cause the object to be displayed on an own screen or not.<br /> <br /> PUBSCREEN<br /> <br /> NAME/A<br /> Cause the object to be displayed on the specified public screen.<br /> <br /> SNAPSHOT<br /> Save the current window position to ENVARC:MultiView/&lt;screen name&gt;.<br /> <br /> GETCURRENTDIR<br /> Return the current directory for the current object.<br /> <br /> GETFILEINFO<br /> Get the file information for the current object.<br /> <br /> GETOBJECTINFO<br /> <br /> VAR/S,STEM/K<br /> Return information about the current object.<br /> <br /> VAR causes the information to be returned in RESULT.<br /> <br /> &quot;name&quot;,&quot;basename&quot;,&quot;group&quot;,&quot;id&quot;<br /> <br /> STEM causes the information to be returned in the named stem variable.<br /> <br /> stem.filename file name of the current object.<br /> stem.name object type name.<br /> stem.basename object type basename.<br /> stem.group object type group.<br /> stem.id object type id.<br /> <br /> MINIMUMSIZE<br /> Resize the object's window to its minimum size.<br /> <br /> NORMALSIZE<br /> Resize the object's window to its nominal size.<br /> <br /> MAXIMUMSIZE<br /> Resize the object's window to its maximum size.<br /> <br /> WINDOWTOFRONT<br /> Bring the object's window to front.<br /> <br /> WINDOWTOBACK<br /> Send the object's window to back.<br /> <br /> ACTIVATEWINDOW<br /> Activate the object's window.<br /> <br /> SCREENTOFRONT<br /> Bring the object's screen to front.<br /> <br /> SCREENTOBACK<br /> Send the object's screen to back.<br /> <br /> BEEPSCREEN<br /> Cause a display beep on the object's screen.<br /> <br /> NEXT<br /> <br /> ''Note: only when viewing an Amigaguide file.''<br /> <br /> Jumps to the next node in the guide.<br /> <br /> PREVIOUS<br /> <br /> Note: only when viewing an Amigaguide file.<br /> <br /> Jumps to the previous node in the guide.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=MultiView&diff=7667 MultiView 2014-05-05T15:41:00Z <p>Philippe Ferrucci: /* Command line arguments */</p> <hr /> <div>= Introduction =<br /> <br /> Multiview can read any file for which there is a descriptor file in Devs:Datatypes. These tell Multiview (and any other programs written to take advantage of datatypes) how to load the various types of files.<br /> <br /> = Command line arguments =<br /> <br /> ; FILE<br /> : Name of the file you want to be displayed/played by Multiview. Alternatively you can specify a volume or directory name that will be used by Multiview as the current directory when it opens its requester.<br /> : Note: this argument is optional as Multiview can be used to display the content of a clipboard unit instead of a file.<br /> <br /> ; CLIPBOARD/S<br /> : Argument that will make Multiview display the content of the clipboard unit specified with the CLIPUNIT argument.<br /> <br /> ; CLIPUNIT/K/N<br /> : Clipboard unit you want to display with Multiview. Default is 0.<br /> <br /> ; SCREEN/S<br /> : Arguments that will make Multiview open its view window on its own screen.<br /> <br /> ; PUBSCREEN/K<br /> : Name of a public screen you want Multiview to open its window on.<br /> : Note: usage of the SCREEN switch is implicit so it is not needed. If you quit the program which is owner of the public screen while Multiview is still opened the application will probably crash as it is not necessarily aware of an alien windows opened on its screen.<br /> <br /> ; REQUESTER/S<br /> <br /> ; BOOKMARK/S<br /> : Reads file ENV:MultiView.bookmark<br /> <br /> ; FONTNAME/K<br /> : Name of the font Multiview will use to display text and AmigaGuide files. If none is specified here Multiview will use the default system font.<br /> <br /> ; FONTSIZE/K/N<br /> : Size of the font Multiview will use to display text and AmigaGuide files. If none is specified here Multiview will use the default system font.<br /> <br /> ; CHARSET/K<br /> : Charset to use to display text and AmigaGuide files.<br /> <br /> ; BACKDROP/S<br /> : When this argument is used Multiview will open its display window in backdrop mode.<br /> <br /> ; WINDOW/S<br /> : By default when running Multiview with no arguments, it will open a requester the user can use to select a file to load. With the WINDOW switch Multiview will open with a blank window and no loaded file. The user will have to select Open in the Project menu to select a file to load in Multiview.<br /> <br /> ; PORTNAME/K<br /> : Name of the AREXX port to create. By default the port name is MULTIVIEW.n with &quot;n&quot; being an incremental number starting from 1. It is incremented for each started Multiview instance.<br /> <br /> ; IMMEDIATE/S<br /> : Indicate whether the object should immediately begin playing. Defaults to FALSE.<br /> <br /> ; REPEAT/S<br /> : Indicate that the object should repeat playing. Defaults to FALSE.<br /> <br /> ; PRTUNIT/K/N<br /> <br /> ; WINDOWLEFT/K/N,WINDOWTOP/K/N,WINDOWWIDTH/K/N,WINDOWHEIGHT/K/N<br /> <br /> ; AUTORESIZE/S<br /> <br /> = Command line examples =<br /> <br /> Multiview...<br /> <br /> = ARexx Commands =<br /> <br /> OPEN<br /> <br /> NAME/K,CLIPBOARD/S,CLIPUNIT/K/N<br /> Open a file, or the contents of the specified clipboard unit.<br /> <br /> RELOAD<br /> Reload the current object.<br /> <br /> SAVEAS<br /> <br /> NAME/K,IFF/S<br /> Save the current object to disk. The IFF switch is used to force the<br /> save to be IFF instead of RAW (local format).<br /> <br /> PRINT<br /> Print the current object.<br /> <br /> ABOUT<br /> Display a requester with information about the current object.<br /> <br /> QUIT<br /> Quit MultiView.<br /> <br /> MARK<br /> Start Mark mode.<br /> <br /> COPY<br /> Copy the currently selected block (or the whole object if no<br /> selected block exists) to the clipboard.<br /> <br /> PASTE<br /> <br /> UNIT/N<br /> Open the contents of the specified clipboard unit. PASTE &lt;n&gt; is a<br /> shortcut for OPEN CLIPBOARD CLIPUNIT &lt;n&gt;.<br /> <br /> CLEARSELECTED<br /> Deselect the currently selected block, if one exists.<br /> <br /> GETTRIGGERINFO<br /> <br /> VAR/S,STEM/K<br /> Provide a list of trigger methods that the current object supports.<br /> <br /> VAR causes the information to be returned in RESULT.<br /> <br /> STEM causes the information to be returned in the named stem variable.<br /> The following values are supported:<br /> <br /> stem.count number of elements in the array.<br /> stem.n.label label<br /> stem.n.command command<br /> stem.n.method method<br /> <br /> DOTRIGGERMETHOD<br /> <br /> METHOD/A<br /> Perform a trigger method on the current object.<br /> <br /> SCREEN<br /> <br /> TRUE/S,FALSE/S<br /> Cause the object to be displayed on an own screen or not.<br /> <br /> PUBSCREEN<br /> <br /> NAME/A<br /> Cause the object to be displayed on the specified public screen.<br /> <br /> SNAPSHOT<br /> Save the current window position to ENVARC:MultiView/&lt;screen name&gt;.<br /> <br /> GETCURRENTDIR<br /> Return the current directory for the current object.<br /> <br /> GETFILEINFO<br /> Get the file information for the current object.<br /> <br /> GETOBJECTINFO<br /> <br /> VAR/S,STEM/K<br /> Return information about the current object.<br /> <br /> VAR causes the information to be returned in RESULT.<br /> <br /> &quot;name&quot;,&quot;basename&quot;,&quot;group&quot;,&quot;id&quot;<br /> <br /> STEM causes the information to be returned in the named stem variable.<br /> <br /> stem.filename file name of the current object.<br /> stem.name object type name.<br /> stem.basename object type basename.<br /> stem.group object type group.<br /> stem.id object type id.<br /> <br /> MINIMUMSIZE<br /> Resize the object's window to its minimum size.<br /> <br /> NORMALSIZE<br /> Resize the object's window to its nominal size.<br /> <br /> MAXIMUMSIZE<br /> Resize the object's window to its maximum size.<br /> <br /> WINDOWTOFRONT<br /> Bring the object's window to front.<br /> <br /> WINDOWTOBACK<br /> Send the object's window to back.<br /> <br /> ACTIVATEWINDOW<br /> Activate the object's window.<br /> <br /> SCREENTOFRONT<br /> Bring the object's screen to front.<br /> <br /> SCREENTOBACK<br /> Send the object's screen to back.<br /> <br /> BEEPSCREEN<br /> Cause a display beep on the object's screen.<br /> <br /> NEXT<br /> <br /> ''Note: only when viewing an Amigaguide file.''<br /> <br /> Jumps to the next node in the guide.<br /> <br /> PREVIOUS<br /> <br /> Note: only when viewing an Amigaguide file.<br /> <br /> Jumps to the previous node in the guide.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=MultiView&diff=7666 MultiView 2014-05-05T14:44:47Z <p>Philippe Ferrucci: /* Command line arguments */</p> <hr /> <div>= Introduction =<br /> <br /> Multiview can read any file for which there is a descriptor file in Devs:Datatypes. These tell Multiview (and any other programs written to take advantage of datatypes) how to load the various types of files.<br /> <br /> = Command line arguments =<br /> <br /> ; FILE<br /> : Name of the file you want to be displayed/played by Multiview. Alternatively you can specify a volume or directory name that will be used by Multiview as the current directory when it opens its requester.<br /> : Note: this argument is optional as Multiview can be used to display the content of a clipboard unit instead of a file.<br /> <br /> ; CLIPBOARD/S<br /> : Argument that will make Multiview display the content of the clipboard unit specified with the CLIPUNIT argument.<br /> <br /> ; CLIPUNIT/K/N<br /> : Clipboard unit you want to display with Multiview. Default is 0.<br /> <br /> ; SCREEN/S<br /> : Arguments that will make Multiview open its view window on its own screen.<br /> <br /> ; PUBSCREEN/K<br /> : Name of a public screen you want Multiview to open its window on.<br /> : Note: usage of the SCREEN switch is implicit so it is not needed. If you quit the program which is owner of the public screen while Multiview is still opened the application will probably crash as it is not necessarily aware of an alien windows opened on its screen.<br /> <br /> ; REQUESTER/S<br /> <br /> ; BOOKMARK/S<br /> : Reads file ENV:MultiView.bookmark<br /> <br /> ; FONTNAME/K<br /> : Name of the font Multiview will use to display text and AmigaGuide files. If none is specified here Multiview will use the default system font.<br /> <br /> ; FONTSIZE/K/N<br /> : Size of the font Multiview will use to display text and AmigaGuide files. If none is specified here Multiview will use the default system font.<br /> <br /> ; CHARSET/K<br /> : Charset to use to display text and AmigaGuide files.<br /> <br /> ; BACKDROP/S<br /> : When this argument is used Multiview will open its display window in backdrop mode.<br /> <br /> ; WINDOW/S<br /> : By default when running Multiview with no arguments, it will open a requester the user can use to select a file to load. With the WINDOW switch Multiview will open with a blank window and no loaded file. The user will have to select Open in the Project menu to select a file to load in Multiview.<br /> <br /> ; PORTNAME/K<br /> : Name of the AREXX port to create. By default the port name is MULTIVIEW.n (&quot;n&quot; being an incremental number starting from 1)<br /> <br /> ; IMMEDIATE/S<br /> : <br /> <br /> ; REPEAT/S<br /> <br /> ; PRTUNIT/K/N<br /> <br /> ; WINDOWLEFT/K/N,WINDOWTOP/K/N,WINDOWWIDTH/K/N,WINDOWHEIGHT/K/N<br /> <br /> ; AUTORESIZE/S<br /> <br /> = Command line examples =<br /> <br /> Multiview...<br /> <br /> = ARexx Commands =<br /> <br /> OPEN<br /> <br /> NAME/K,CLIPBOARD/S,CLIPUNIT/K/N<br /> Open a file, or the contents of the specified clipboard unit.<br /> <br /> RELOAD<br /> Reload the current object.<br /> <br /> SAVEAS<br /> <br /> NAME/K,IFF/S<br /> Save the current object to disk. The IFF switch is used to force the<br /> save to be IFF instead of RAW (local format).<br /> <br /> PRINT<br /> Print the current object.<br /> <br /> ABOUT<br /> Display a requester with information about the current object.<br /> <br /> QUIT<br /> Quit MultiView.<br /> <br /> MARK<br /> Start Mark mode.<br /> <br /> COPY<br /> Copy the currently selected block (or the whole object if no<br /> selected block exists) to the clipboard.<br /> <br /> PASTE<br /> <br /> UNIT/N<br /> Open the contents of the specified clipboard unit. PASTE &lt;n&gt; is a<br /> shortcut for OPEN CLIPBOARD CLIPUNIT &lt;n&gt;.<br /> <br /> CLEARSELECTED<br /> Deselect the currently selected block, if one exists.<br /> <br /> GETTRIGGERINFO<br /> <br /> VAR/S,STEM/K<br /> Provide a list of trigger methods that the current object supports.<br /> <br /> VAR causes the information to be returned in RESULT.<br /> <br /> STEM causes the information to be returned in the named stem variable.<br /> The following values are supported:<br /> <br /> stem.count number of elements in the array.<br /> stem.n.label label<br /> stem.n.command command<br /> stem.n.method method<br /> <br /> DOTRIGGERMETHOD<br /> <br /> METHOD/A<br /> Perform a trigger method on the current object.<br /> <br /> SCREEN<br /> <br /> TRUE/S,FALSE/S<br /> Cause the object to be displayed on an own screen or not.<br /> <br /> PUBSCREEN<br /> <br /> NAME/A<br /> Cause the object to be displayed on the specified public screen.<br /> <br /> SNAPSHOT<br /> Save the current window position to ENVARC:MultiView/&lt;screen name&gt;.<br /> <br /> GETCURRENTDIR<br /> Return the current directory for the current object.<br /> <br /> GETFILEINFO<br /> Get the file information for the current object.<br /> <br /> GETOBJECTINFO<br /> <br /> VAR/S,STEM/K<br /> Return information about the current object.<br /> <br /> VAR causes the information to be returned in RESULT.<br /> <br /> &quot;name&quot;,&quot;basename&quot;,&quot;group&quot;,&quot;id&quot;<br /> <br /> STEM causes the information to be returned in the named stem variable.<br /> <br /> stem.filename file name of the current object.<br /> stem.name object type name.<br /> stem.basename object type basename.<br /> stem.group object type group.<br /> stem.id object type id.<br /> <br /> MINIMUMSIZE<br /> Resize the object's window to its minimum size.<br /> <br /> NORMALSIZE<br /> Resize the object's window to its nominal size.<br /> <br /> MAXIMUMSIZE<br /> Resize the object's window to its maximum size.<br /> <br /> WINDOWTOFRONT<br /> Bring the object's window to front.<br /> <br /> WINDOWTOBACK<br /> Send the object's window to back.<br /> <br /> ACTIVATEWINDOW<br /> Activate the object's window.<br /> <br /> SCREENTOFRONT<br /> Bring the object's screen to front.<br /> <br /> SCREENTOBACK<br /> Send the object's screen to back.<br /> <br /> BEEPSCREEN<br /> Cause a display beep on the object's screen.<br /> <br /> NEXT<br /> <br /> ''Note: only when viewing an Amigaguide file.''<br /> <br /> Jumps to the next node in the guide.<br /> <br /> PREVIOUS<br /> <br /> Note: only when viewing an Amigaguide file.<br /> <br /> Jumps to the previous node in the guide.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=MultiView&diff=7665 MultiView 2014-05-05T14:24:47Z <p>Philippe Ferrucci: /* Command line arguments */</p> <hr /> <div>= Introduction =<br /> <br /> Multiview can read any file for which there is a descriptor file in Devs:Datatypes. These tell Multiview (and any other programs written to take advantage of datatypes) how to load the various types of files.<br /> <br /> = Command line arguments =<br /> <br /> ; FILE<br /> : Name of the file you want to be displayed/played by Multiview.<br /> : Note: this argument is optional as Multiview can be used to display the content of a clipboard unit instead of a file.<br /> <br /> ; CLIPBOARD/S<br /> : Argument that will make Multiview display the content of the clipboard unit specified with the CLIPUNIT argument.<br /> <br /> ; CLIPUNIT/K/N<br /> : Clipboard unit you want to display with Multiview. Default is 0.<br /> <br /> ; SCREEN/S<br /> : Arguments that will make Multiview open its view window on its own screen.<br /> <br /> ; PUBSCREEN/K<br /> : Name of a public screen you want Multiview to open its window on.<br /> : Note: usage of the SCREEN switch is implicit so it is not needed. If you quit the program which is owner of the public screen while Multiview is still opened the application will probably crash as it is not necessarily aware of an alien windows opened on its screen.<br /> <br /> ; REQUESTER/S<br /> <br /> ; BOOKMARK/S<br /> : Reads file ENV:MultiView.bookmark<br /> <br /> ; FONTNAME/K<br /> : Name of the font Multiview will use to display text and AmigaGuide files. If none is specified here Multiview will use the default system font.<br /> <br /> ; FONTSIZE/K/N<br /> : Size of the font Multiview will use to display text and AmigaGuide files. If none is specified here Multiview will use the default system font.<br /> <br /> ; CHARSET/K<br /> : Charset to use to display text and AmigaGuide files.<br /> <br /> ; BACKDROP/S<br /> : When this argument is used Multiview will open its display window in backdrop mode.<br /> <br /> ; WINDOW/S<br /> <br /> ; PORTNAME/K<br /> <br /> ; IMMEDIATE/S<br /> <br /> ; REPEAT/S<br /> <br /> ; PRTUNIT/K/N<br /> <br /> ; WINDOWLEFT/K/N,WINDOWTOP/K/N,WINDOWWIDTH/K/N,WINDOWHEIGHT/K/N<br /> <br /> ; AUTORESIZE/S<br /> <br /> = Command line examples =<br /> <br /> Multiview...<br /> <br /> = ARexx Commands =<br /> <br /> OPEN<br /> <br /> NAME/K,CLIPBOARD/S,CLIPUNIT/K/N<br /> Open a file, or the contents of the specified clipboard unit.<br /> <br /> RELOAD<br /> Reload the current object.<br /> <br /> SAVEAS<br /> <br /> NAME/K,IFF/S<br /> Save the current object to disk. The IFF switch is used to force the<br /> save to be IFF instead of RAW (local format).<br /> <br /> PRINT<br /> Print the current object.<br /> <br /> ABOUT<br /> Display a requester with information about the current object.<br /> <br /> QUIT<br /> Quit MultiView.<br /> <br /> MARK<br /> Start Mark mode.<br /> <br /> COPY<br /> Copy the currently selected block (or the whole object if no<br /> selected block exists) to the clipboard.<br /> <br /> PASTE<br /> <br /> UNIT/N<br /> Open the contents of the specified clipboard unit. PASTE &lt;n&gt; is a<br /> shortcut for OPEN CLIPBOARD CLIPUNIT &lt;n&gt;.<br /> <br /> CLEARSELECTED<br /> Deselect the currently selected block, if one exists.<br /> <br /> GETTRIGGERINFO<br /> <br /> VAR/S,STEM/K<br /> Provide a list of trigger methods that the current object supports.<br /> <br /> VAR causes the information to be returned in RESULT.<br /> <br /> STEM causes the information to be returned in the named stem variable.<br /> The following values are supported:<br /> <br /> stem.count number of elements in the array.<br /> stem.n.label label<br /> stem.n.command command<br /> stem.n.method method<br /> <br /> DOTRIGGERMETHOD<br /> <br /> METHOD/A<br /> Perform a trigger method on the current object.<br /> <br /> SCREEN<br /> <br /> TRUE/S,FALSE/S<br /> Cause the object to be displayed on an own screen or not.<br /> <br /> PUBSCREEN<br /> <br /> NAME/A<br /> Cause the object to be displayed on the specified public screen.<br /> <br /> SNAPSHOT<br /> Save the current window position to ENVARC:MultiView/&lt;screen name&gt;.<br /> <br /> GETCURRENTDIR<br /> Return the current directory for the current object.<br /> <br /> GETFILEINFO<br /> Get the file information for the current object.<br /> <br /> GETOBJECTINFO<br /> <br /> VAR/S,STEM/K<br /> Return information about the current object.<br /> <br /> VAR causes the information to be returned in RESULT.<br /> <br /> &quot;name&quot;,&quot;basename&quot;,&quot;group&quot;,&quot;id&quot;<br /> <br /> STEM causes the information to be returned in the named stem variable.<br /> <br /> stem.filename file name of the current object.<br /> stem.name object type name.<br /> stem.basename object type basename.<br /> stem.group object type group.<br /> stem.id object type id.<br /> <br /> MINIMUMSIZE<br /> Resize the object's window to its minimum size.<br /> <br /> NORMALSIZE<br /> Resize the object's window to its nominal size.<br /> <br /> MAXIMUMSIZE<br /> Resize the object's window to its maximum size.<br /> <br /> WINDOWTOFRONT<br /> Bring the object's window to front.<br /> <br /> WINDOWTOBACK<br /> Send the object's window to back.<br /> <br /> ACTIVATEWINDOW<br /> Activate the object's window.<br /> <br /> SCREENTOFRONT<br /> Bring the object's screen to front.<br /> <br /> SCREENTOBACK<br /> Send the object's screen to back.<br /> <br /> BEEPSCREEN<br /> Cause a display beep on the object's screen.<br /> <br /> NEXT<br /> <br /> ''Note: only when viewing an Amigaguide file.''<br /> <br /> Jumps to the next node in the guide.<br /> <br /> PREVIOUS<br /> <br /> Note: only when viewing an Amigaguide file.<br /> <br /> Jumps to the previous node in the guide.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=MultiView&diff=7664 MultiView 2014-05-05T14:20:10Z <p>Philippe Ferrucci: /* Command line arguments */</p> <hr /> <div>= Introduction =<br /> <br /> Multiview can read any file for which there is a descriptor file in Devs:Datatypes. These tell Multiview (and any other programs written to take advantage of datatypes) how to load the various types of files.<br /> <br /> = Command line arguments =<br /> <br /> ; FILE<br /> : Name of the file you want to be displayed/played by Multiview.<br /> : Note: this argument is optional as Multiview can be used to display the content of a clipboard unit instead of a file.<br /> <br /> ; CLIPBOARD/S<br /> : Argument that will make Multiview display the content of the clipboard unit specified with the CLIPUNIT argument.<br /> <br /> ; CLIPUNIT/K/N<br /> : Clipboard unit you want to display with Multiview. Default is 0.<br /> <br /> ; SCREEN/S<br /> : Arguments that will make Multiview open its view window on its own screen.<br /> <br /> ; PUBSCREEN/K<br /> : Name of a public screen you want Multiview to open its window on.<br /> : Note: usage of the SCREEN switch is implicit so it is not needed. If you quit the program which is owner of the public screen while Multiview is still opened the application will probably crash as it is not necessarily aware of an alien windows opened on its screen.<br /> <br /> ; REQUESTER/S<br /> <br /> ; BOOKMARK/S<br /> : Reads file ENV:MultiView.bookmark<br /> <br /> ; FONTNAME/K<br /> : Name of the font Multiview will use to display text and AmigaGuide files<br /> <br /> ; FONTSIZE/K/N<br /> : Size of the font specified with FONTNAME Multiview will use to display text and AmigaGuide files<br /> <br /> ; CHARSET/K<br /> : Charset to use to display text and AmigaGuide files<br /> <br /> ; BACKDROP/S<br /> <br /> ; WINDOW/S<br /> <br /> ; PORTNAME/K<br /> <br /> ; IMMEDIATE/S<br /> <br /> ; REPEAT/S<br /> <br /> ; PRTUNIT/K/N<br /> <br /> ; WINDOWLEFT/K/N,WINDOWTOP/K/N,WINDOWWIDTH/K/N,WINDOWHEIGHT/K/N<br /> <br /> ; AUTORESIZE/S<br /> <br /> = Command line examples =<br /> <br /> Multiview...<br /> <br /> = ARexx Commands =<br /> <br /> OPEN<br /> <br /> NAME/K,CLIPBOARD/S,CLIPUNIT/K/N<br /> Open a file, or the contents of the specified clipboard unit.<br /> <br /> RELOAD<br /> Reload the current object.<br /> <br /> SAVEAS<br /> <br /> NAME/K,IFF/S<br /> Save the current object to disk. The IFF switch is used to force the<br /> save to be IFF instead of RAW (local format).<br /> <br /> PRINT<br /> Print the current object.<br /> <br /> ABOUT<br /> Display a requester with information about the current object.<br /> <br /> QUIT<br /> Quit MultiView.<br /> <br /> MARK<br /> Start Mark mode.<br /> <br /> COPY<br /> Copy the currently selected block (or the whole object if no<br /> selected block exists) to the clipboard.<br /> <br /> PASTE<br /> <br /> UNIT/N<br /> Open the contents of the specified clipboard unit. PASTE &lt;n&gt; is a<br /> shortcut for OPEN CLIPBOARD CLIPUNIT &lt;n&gt;.<br /> <br /> CLEARSELECTED<br /> Deselect the currently selected block, if one exists.<br /> <br /> GETTRIGGERINFO<br /> <br /> VAR/S,STEM/K<br /> Provide a list of trigger methods that the current object supports.<br /> <br /> VAR causes the information to be returned in RESULT.<br /> <br /> STEM causes the information to be returned in the named stem variable.<br /> The following values are supported:<br /> <br /> stem.count number of elements in the array.<br /> stem.n.label label<br /> stem.n.command command<br /> stem.n.method method<br /> <br /> DOTRIGGERMETHOD<br /> <br /> METHOD/A<br /> Perform a trigger method on the current object.<br /> <br /> SCREEN<br /> <br /> TRUE/S,FALSE/S<br /> Cause the object to be displayed on an own screen or not.<br /> <br /> PUBSCREEN<br /> <br /> NAME/A<br /> Cause the object to be displayed on the specified public screen.<br /> <br /> SNAPSHOT<br /> Save the current window position to ENVARC:MultiView/&lt;screen name&gt;.<br /> <br /> GETCURRENTDIR<br /> Return the current directory for the current object.<br /> <br /> GETFILEINFO<br /> Get the file information for the current object.<br /> <br /> GETOBJECTINFO<br /> <br /> VAR/S,STEM/K<br /> Return information about the current object.<br /> <br /> VAR causes the information to be returned in RESULT.<br /> <br /> &quot;name&quot;,&quot;basename&quot;,&quot;group&quot;,&quot;id&quot;<br /> <br /> STEM causes the information to be returned in the named stem variable.<br /> <br /> stem.filename file name of the current object.<br /> stem.name object type name.<br /> stem.basename object type basename.<br /> stem.group object type group.<br /> stem.id object type id.<br /> <br /> MINIMUMSIZE<br /> Resize the object's window to its minimum size.<br /> <br /> NORMALSIZE<br /> Resize the object's window to its nominal size.<br /> <br /> MAXIMUMSIZE<br /> Resize the object's window to its maximum size.<br /> <br /> WINDOWTOFRONT<br /> Bring the object's window to front.<br /> <br /> WINDOWTOBACK<br /> Send the object's window to back.<br /> <br /> ACTIVATEWINDOW<br /> Activate the object's window.<br /> <br /> SCREENTOFRONT<br /> Bring the object's screen to front.<br /> <br /> SCREENTOBACK<br /> Send the object's screen to back.<br /> <br /> BEEPSCREEN<br /> Cause a display beep on the object's screen.<br /> <br /> NEXT<br /> <br /> ''Note: only when viewing an Amigaguide file.''<br /> <br /> Jumps to the next node in the guide.<br /> <br /> PREVIOUS<br /> <br /> Note: only when viewing an Amigaguide file.<br /> <br /> Jumps to the previous node in the guide.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=MultiView&diff=7663 MultiView 2014-05-05T09:21:33Z <p>Philippe Ferrucci: /* Command line arguments */</p> <hr /> <div>= Introduction =<br /> <br /> Multiview can read any file for which there is a descriptor file in Devs:Datatypes. These tell Multiview (and any other programs written to take advantage of datatypes) how to load the various types of files.<br /> <br /> = Command line arguments =<br /> <br /> ; FILE<br /> : Name of the file you want to be displayed/played by Multiview.<br /> : Note: this argument is optional as Multiview can be used to display the content of a clipboard unit instead of a file.<br /> <br /> ; CLIPBOARD/S<br /> : Argument that will make Multiview display the content of the clipboard unit specified with the CLIPUNIT argument.<br /> <br /> ; CLIPUNIT/K/N<br /> : Clipboard unit you want to display with Multiview. Default is 0.<br /> <br /> ; SCREEN/S<br /> : Arguments that will make Multiview open its view window on its own screen.<br /> <br /> ; PUBSCREEN/K<br /> : Name of a public screen you want Multiview to open its window on.<br /> : Note: usage of the SCREEN switch is implicit so it is not needed. If you quit the program which is owner of the public screen while Multiview is still opened the application will probably crash as it is not necessarily aware of an alien windows opened on its screen.<br /> <br /> ; REQUESTER/S<br /> <br /> ; BOOKMARK/S<br /> : Reads file ENV:MultiView.bookmark<br /> <br /> ; FONTNAME/K<br /> <br /> ; FONTSIZE/K/N<br /> <br /> ; CHARSET/K<br /> <br /> ; BACKDROP/S<br /> <br /> ; WINDOW/S<br /> <br /> ; PORTNAME/K<br /> <br /> ; IMMEDIATE/S<br /> <br /> ; REPEAT/S<br /> <br /> ; PRTUNIT/K/N<br /> <br /> ; WINDOWLEFT/K/N,WINDOWTOP/K/N,WINDOWWIDTH/K/N,WINDOWHEIGHT/K/N<br /> <br /> ; AUTORESIZE/S<br /> <br /> = Command line examples =<br /> <br /> Multiview...<br /> <br /> = ARexx Commands =<br /> <br /> OPEN<br /> <br /> NAME/K,CLIPBOARD/S,CLIPUNIT/K/N<br /> Open a file, or the contents of the specified clipboard unit.<br /> <br /> RELOAD<br /> Reload the current object.<br /> <br /> SAVEAS<br /> <br /> NAME/K,IFF/S<br /> Save the current object to disk. The IFF switch is used to force the<br /> save to be IFF instead of RAW (local format).<br /> <br /> PRINT<br /> Print the current object.<br /> <br /> ABOUT<br /> Display a requester with information about the current object.<br /> <br /> QUIT<br /> Quit MultiView.<br /> <br /> MARK<br /> Start Mark mode.<br /> <br /> COPY<br /> Copy the currently selected block (or the whole object if no<br /> selected block exists) to the clipboard.<br /> <br /> PASTE<br /> <br /> UNIT/N<br /> Open the contents of the specified clipboard unit. PASTE &lt;n&gt; is a<br /> shortcut for OPEN CLIPBOARD CLIPUNIT &lt;n&gt;.<br /> <br /> CLEARSELECTED<br /> Deselect the currently selected block, if one exists.<br /> <br /> GETTRIGGERINFO<br /> <br /> VAR/S,STEM/K<br /> Provide a list of trigger methods that the current object supports.<br /> <br /> VAR causes the information to be returned in RESULT.<br /> <br /> STEM causes the information to be returned in the named stem variable.<br /> The following values are supported:<br /> <br /> stem.count number of elements in the array.<br /> stem.n.label label<br /> stem.n.command command<br /> stem.n.method method<br /> <br /> DOTRIGGERMETHOD<br /> <br /> METHOD/A<br /> Perform a trigger method on the current object.<br /> <br /> SCREEN<br /> <br /> TRUE/S,FALSE/S<br /> Cause the object to be displayed on an own screen or not.<br /> <br /> PUBSCREEN<br /> <br /> NAME/A<br /> Cause the object to be displayed on the specified public screen.<br /> <br /> SNAPSHOT<br /> Save the current window position to ENVARC:MultiView/&lt;screen name&gt;.<br /> <br /> GETCURRENTDIR<br /> Return the current directory for the current object.<br /> <br /> GETFILEINFO<br /> Get the file information for the current object.<br /> <br /> GETOBJECTINFO<br /> <br /> VAR/S,STEM/K<br /> Return information about the current object.<br /> <br /> VAR causes the information to be returned in RESULT.<br /> <br /> &quot;name&quot;,&quot;basename&quot;,&quot;group&quot;,&quot;id&quot;<br /> <br /> STEM causes the information to be returned in the named stem variable.<br /> <br /> stem.filename file name of the current object.<br /> stem.name object type name.<br /> stem.basename object type basename.<br /> stem.group object type group.<br /> stem.id object type id.<br /> <br /> MINIMUMSIZE<br /> Resize the object's window to its minimum size.<br /> <br /> NORMALSIZE<br /> Resize the object's window to its nominal size.<br /> <br /> MAXIMUMSIZE<br /> Resize the object's window to its maximum size.<br /> <br /> WINDOWTOFRONT<br /> Bring the object's window to front.<br /> <br /> WINDOWTOBACK<br /> Send the object's window to back.<br /> <br /> ACTIVATEWINDOW<br /> Activate the object's window.<br /> <br /> SCREENTOFRONT<br /> Bring the object's screen to front.<br /> <br /> SCREENTOBACK<br /> Send the object's screen to back.<br /> <br /> BEEPSCREEN<br /> Cause a display beep on the object's screen.<br /> <br /> NEXT<br /> <br /> ''Note: only when viewing an Amigaguide file.''<br /> <br /> Jumps to the next node in the guide.<br /> <br /> PREVIOUS<br /> <br /> Note: only when viewing an Amigaguide file.<br /> <br /> Jumps to the previous node in the guide.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=MultiView&diff=7662 MultiView 2014-05-04T17:25:49Z <p>Philippe Ferrucci: /* Command line arguments */</p> <hr /> <div>= Introduction =<br /> <br /> Multiview can read any file for which there is a descriptor file in Devs:Datatypes. These tell Multiview (and any other programs written to take advantage of datatypes) how to load the various types of files.<br /> <br /> = Command line arguments =<br /> <br /> ; FILE<br /> : Name of the file you want to be displayed/played by Multiview.<br /> <br /> ; CLIPBOARD/S<br /> : <br /> <br /> ; CLIPUNIT/K/N<br /> <br /> ; SCREEN/S<br /> <br /> ; PUBSCREEN/K<br /> <br /> ; REQUESTER/S<br /> <br /> ; BOOKMARK/S<br /> <br /> ; FONTNAME/K<br /> <br /> ; FONTSIZE/K/N<br /> <br /> ; CHARSET/K<br /> <br /> ; BACKDROP/S<br /> <br /> ; WINDOW/S<br /> <br /> ; PORTNAME/K<br /> <br /> ; IMMEDIATE/S<br /> <br /> ; REPEAT/S<br /> <br /> ; PRTUNIT/K/N<br /> <br /> ; WINDOWLEFT/K/N,WINDOWTOP/K/N,WINDOWWIDTH/K/N,WINDOWHEIGHT/K/N<br /> <br /> ; AUTORESIZE/S<br /> <br /> = Command line examples =<br /> <br /> Multiview...<br /> <br /> = ARexx Commands =<br /> <br /> OPEN<br /> <br /> NAME/K,CLIPBOARD/S,CLIPUNIT/K/N<br /> Open a file, or the contents of the specified clipboard unit.<br /> <br /> RELOAD<br /> Reload the current object.<br /> <br /> SAVEAS<br /> <br /> NAME/K,IFF/S<br /> Save the current object to disk. The IFF switch is used to force the<br /> save to be IFF instead of RAW (local format).<br /> <br /> PRINT<br /> Print the current object.<br /> <br /> ABOUT<br /> Display a requester with information about the current object.<br /> <br /> QUIT<br /> Quit MultiView.<br /> <br /> MARK<br /> Start Mark mode.<br /> <br /> COPY<br /> Copy the currently selected block (or the whole object if no<br /> selected block exists) to the clipboard.<br /> <br /> PASTE<br /> <br /> UNIT/N<br /> Open the contents of the specified clipboard unit. PASTE &lt;n&gt; is a<br /> shortcut for OPEN CLIPBOARD CLIPUNIT &lt;n&gt;.<br /> <br /> CLEARSELECTED<br /> Deselect the currently selected block, if one exists.<br /> <br /> GETTRIGGERINFO<br /> <br /> VAR/S,STEM/K<br /> Provide a list of trigger methods that the current object supports.<br /> <br /> VAR causes the information to be returned in RESULT.<br /> <br /> STEM causes the information to be returned in the named stem variable.<br /> The following values are supported:<br /> <br /> stem.count number of elements in the array.<br /> stem.n.label label<br /> stem.n.command command<br /> stem.n.method method<br /> <br /> DOTRIGGERMETHOD<br /> <br /> METHOD/A<br /> Perform a trigger method on the current object.<br /> <br /> SCREEN<br /> <br /> TRUE/S,FALSE/S<br /> Cause the object to be displayed on an own screen or not.<br /> <br /> PUBSCREEN<br /> <br /> NAME/A<br /> Cause the object to be displayed on the specified public screen.<br /> <br /> SNAPSHOT<br /> Save the current window position to ENVARC:MultiView/&lt;screen name&gt;.<br /> <br /> GETCURRENTDIR<br /> Return the current directory for the current object.<br /> <br /> GETFILEINFO<br /> Get the file information for the current object.<br /> <br /> GETOBJECTINFO<br /> <br /> VAR/S,STEM/K<br /> Return information about the current object.<br /> <br /> VAR causes the information to be returned in RESULT.<br /> <br /> &quot;name&quot;,&quot;basename&quot;,&quot;group&quot;,&quot;id&quot;<br /> <br /> STEM causes the information to be returned in the named stem variable.<br /> <br /> stem.filename file name of the current object.<br /> stem.name object type name.<br /> stem.basename object type basename.<br /> stem.group object type group.<br /> stem.id object type id.<br /> <br /> MINIMUMSIZE<br /> Resize the object's window to its minimum size.<br /> <br /> NORMALSIZE<br /> Resize the object's window to its nominal size.<br /> <br /> MAXIMUMSIZE<br /> Resize the object's window to its maximum size.<br /> <br /> WINDOWTOFRONT<br /> Bring the object's window to front.<br /> <br /> WINDOWTOBACK<br /> Send the object's window to back.<br /> <br /> ACTIVATEWINDOW<br /> Activate the object's window.<br /> <br /> SCREENTOFRONT<br /> Bring the object's screen to front.<br /> <br /> SCREENTOBACK<br /> Send the object's screen to back.<br /> <br /> BEEPSCREEN<br /> Cause a display beep on the object's screen.<br /> <br /> NEXT<br /> <br /> ''Note: only when viewing an Amigaguide file.''<br /> <br /> Jumps to the next node in the guide.<br /> <br /> PREVIOUS<br /> <br /> Note: only when viewing an Amigaguide file.<br /> <br /> Jumps to the previous node in the guide.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=MultiView&diff=7661 MultiView 2014-05-04T17:15:32Z <p>Philippe Ferrucci: </p> <hr /> <div>= Introduction =<br /> <br /> Multiview can read any file for which there is a descriptor file in Devs:Datatypes. These tell Multiview (and any other programs written to take advantage of datatypes) how to load the various types of files.<br /> <br /> = Command line arguments =<br /> <br /> ; FILE<br /> : Filename you want to be displayed/played by Multiview.<br /> <br /> ; CLIPBOARD/S<br /> : <br /> <br /> ; CLIPUNIT/K/N<br /> <br /> ; SCREEN/S<br /> <br /> ; PUBSCREEN/K<br /> <br /> ; REQUESTER/S<br /> <br /> ; BOOKMARK/S<br /> <br /> ; FONTNAME/K<br /> <br /> ; FONTSIZE/K/N<br /> <br /> ; CHARSET/K<br /> <br /> ; BACKDROP/S<br /> <br /> ; WINDOW/S<br /> <br /> ; PORTNAME/K<br /> <br /> ; IMMEDIATE/S<br /> <br /> ; REPEAT/S<br /> <br /> ; PRTUNIT/K/N<br /> <br /> ; WINDOWLEFT/K/N,WINDOWTOP/K/N,WINDOWWIDTH/K/N,WINDOWHEIGHT/K/N<br /> <br /> ; AUTORESIZE/S<br /> <br /> = Command line examples =<br /> <br /> Multiview...<br /> <br /> = ARexx Commands =<br /> <br /> OPEN<br /> <br /> NAME/K,CLIPBOARD/S,CLIPUNIT/K/N<br /> Open a file, or the contents of the specified clipboard unit.<br /> <br /> RELOAD<br /> Reload the current object.<br /> <br /> SAVEAS<br /> <br /> NAME/K,IFF/S<br /> Save the current object to disk. The IFF switch is used to force the<br /> save to be IFF instead of RAW (local format).<br /> <br /> PRINT<br /> Print the current object.<br /> <br /> ABOUT<br /> Display a requester with information about the current object.<br /> <br /> QUIT<br /> Quit MultiView.<br /> <br /> MARK<br /> Start Mark mode.<br /> <br /> COPY<br /> Copy the currently selected block (or the whole object if no<br /> selected block exists) to the clipboard.<br /> <br /> PASTE<br /> <br /> UNIT/N<br /> Open the contents of the specified clipboard unit. PASTE &lt;n&gt; is a<br /> shortcut for OPEN CLIPBOARD CLIPUNIT &lt;n&gt;.<br /> <br /> CLEARSELECTED<br /> Deselect the currently selected block, if one exists.<br /> <br /> GETTRIGGERINFO<br /> <br /> VAR/S,STEM/K<br /> Provide a list of trigger methods that the current object supports.<br /> <br /> VAR causes the information to be returned in RESULT.<br /> <br /> STEM causes the information to be returned in the named stem variable.<br /> The following values are supported:<br /> <br /> stem.count number of elements in the array.<br /> stem.n.label label<br /> stem.n.command command<br /> stem.n.method method<br /> <br /> DOTRIGGERMETHOD<br /> <br /> METHOD/A<br /> Perform a trigger method on the current object.<br /> <br /> SCREEN<br /> <br /> TRUE/S,FALSE/S<br /> Cause the object to be displayed on an own screen or not.<br /> <br /> PUBSCREEN<br /> <br /> NAME/A<br /> Cause the object to be displayed on the specified public screen.<br /> <br /> SNAPSHOT<br /> Save the current window position to ENVARC:MultiView/&lt;screen name&gt;.<br /> <br /> GETCURRENTDIR<br /> Return the current directory for the current object.<br /> <br /> GETFILEINFO<br /> Get the file information for the current object.<br /> <br /> GETOBJECTINFO<br /> <br /> VAR/S,STEM/K<br /> Return information about the current object.<br /> <br /> VAR causes the information to be returned in RESULT.<br /> <br /> &quot;name&quot;,&quot;basename&quot;,&quot;group&quot;,&quot;id&quot;<br /> <br /> STEM causes the information to be returned in the named stem variable.<br /> <br /> stem.filename file name of the current object.<br /> stem.name object type name.<br /> stem.basename object type basename.<br /> stem.group object type group.<br /> stem.id object type id.<br /> <br /> MINIMUMSIZE<br /> Resize the object's window to its minimum size.<br /> <br /> NORMALSIZE<br /> Resize the object's window to its nominal size.<br /> <br /> MAXIMUMSIZE<br /> Resize the object's window to its maximum size.<br /> <br /> WINDOWTOFRONT<br /> Bring the object's window to front.<br /> <br /> WINDOWTOBACK<br /> Send the object's window to back.<br /> <br /> ACTIVATEWINDOW<br /> Activate the object's window.<br /> <br /> SCREENTOFRONT<br /> Bring the object's screen to front.<br /> <br /> SCREENTOBACK<br /> Send the object's screen to back.<br /> <br /> BEEPSCREEN<br /> Cause a display beep on the object's screen.<br /> <br /> NEXT<br /> <br /> ''Note: only when viewing an Amigaguide file.''<br /> <br /> Jumps to the next node in the guide.<br /> <br /> PREVIOUS<br /> <br /> Note: only when viewing an Amigaguide file.<br /> <br /> Jumps to the previous node in the guide.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=MultiView&diff=7660 MultiView 2014-05-04T16:50:47Z <p>Philippe Ferrucci: Created page with &quot;= Introduction = Multiview can read any file for which there is a descriptor file in Devs:Datatypes. These tell Multiview (and any other programs written to take advantage of...&quot;</p> <hr /> <div>= Introduction =<br /> <br /> Multiview can read any file for which there is a descriptor file in Devs:Datatypes. These tell Multiview (and any other programs written to take advantage of datatypes) how to load the various types of files.<br /> <br /> == ARexx Commands ==<br /> <br /> OPEN<br /> <br /> NAME/K,CLIPBOARD/S,CLIPUNIT/K/N<br /> Open a file, or the contents of the specified clipboard unit.<br /> <br /> RELOAD<br /> ,<br /> Reload the current object.<br /> <br /> SAVEAS<br /> <br /> NAME/K,IFF/S<br /> Save the current object to disk. The IFF switch is used to force the<br /> save to be IFF instead of RAW (local format).<br /> <br /> PRINT<br /> ,<br /> Print the current object.<br /> <br /> ABOUT<br /> ,<br /> Display a requester with information about the current object.<br /> <br /> QUIT<br /> ,<br /> Quit MultiView.<br /> <br /> MARK<br /> ,<br /> Start Mark mode.<br /> <br /> COPY<br /> ,<br /> Copy the currently selected block (or the whole object if no<br /> selected block exists) to the clipboard.<br /> <br /> PASTE<br /> <br /> UNIT/N<br /> Open the contents of the specified clipboard unit. PASTE &lt;n&gt; is a<br /> shortcut for OPEN CLIPBOARD CLIPUNIT &lt;n&gt;.<br /> <br /> CLEARSELECTED<br /> ,<br /> Deselect the currently selected block, if one exists.<br /> <br /> GETTRIGGERINFO<br /> <br /> VAR/S,STEM/K<br /> Provide a list of trigger methods that the current object supports.<br /> <br /> VAR causes the information to be returned in RESULT.<br /> <br /> STEM causes the information to be returned in the named stem variable.<br /> The following values are supported:<br /> <br /> stem.count number of elements in the array.<br /> stem.n.label label<br /> stem.n.command command<br /> stem.n.method method<br /> <br /> DOTRIGGERMETHOD<br /> <br /> METHOD/A<br /> Perform a trigger method on the current object.<br /> <br /> SCREEN<br /> <br /> TRUE/S,FALSE/S<br /> Cause the object to be displayed on an own screen or not.<br /> <br /> PUBSCREEN<br /> <br /> NAME/A<br /> Cause the object to be displayed on the specified public screen.<br /> <br /> SNAPSHOT<br /> ,<br /> Save the current window position to ENVARC:MultiView/&lt;screen name&gt;.<br /> <br /> GETCURRENTDIR<br /> ,<br /> Return the current directory for the current object.<br /> <br /> GETFILEINFO<br /> ,<br /> Get the file information for the current object.<br /> <br /> GETOBJECTINFO<br /> <br /> VAR/S,STEM/K<br /> Return information about the current object.<br /> <br /> VAR causes the information to be returned in RESULT.<br /> <br /> &quot;name&quot;,&quot;basename&quot;,&quot;group&quot;,&quot;id&quot;<br /> <br /> STEM causes the information to be returned in the named stem variable.<br /> <br /> stem.filename file name of the current object.<br /> stem.name object type name.<br /> stem.basename object type basename.<br /> stem.group object type group.<br /> stem.id object type id.<br /> <br /> MINIMUMSIZE<br /> ,<br /> Resize the object's window to its minimum size.<br /> <br /> NORMALSIZE<br /> ,<br /> Resize the object's window to its nominal size.<br /> <br /> MAXIMUMSIZE<br /> ,<br /> Resize the object's window to its maximum size.<br /> <br /> WINDOWTOFRONT<br /> ,<br /> Bring the object's window to front.<br /> <br /> WINDOWTOBACK<br /> ,<br /> Send the object's window to back.<br /> <br /> ACTIVATEWINDOW<br /> ,<br /> Activate the object's window.<br /> <br /> SCREENTOFRONT<br /> ,<br /> Bring the object's screen to front.<br /> <br /> SCREENTOBACK<br /> ,<br /> Send the object's screen to back.<br /> <br /> BEEPSCREEN<br /> ,<br /> Cause a display beep on the object's screen.<br /> <br /> NEXT<br /> <br /> Note: only when viewing an Amigaguide file.<br /> <br /> Jumps to the next node in the guide.<br /> <br /> PREVIOUS<br /> <br /> Note: only when viewing an Amigaguide file.<br /> <br /> Jumps to the previous node in the guide.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=Utilities&diff=7659 Utilities 2014-05-04T16:48:26Z <p>Philippe Ferrucci: /* MultiView */</p> <hr /> <div>= Introduction =<br /> <br /> Below is the list of what is included in a default AmigaOS installation. You can find either programs or a group of &quot;sub-programs&quot; that another program needs. For your convenience they are marked with a &quot;(Dir)&quot; if they represent a directory.<br /> <br /> = AmigaOS SYS:Utilities =<br /> <br /> == AmiGS (Dir) ==<br /> <br /> == AmiPDF (Dir) ==<br /> <br /> == Blankers (Dir) ==<br /> <br /> == bru ==<br /> <br /> == Calculator ==<br /> <br /> == CatComp ==<br /> <br /> == Clock ==<br /> <br /> == Commodities (Dir) ==<br /> <br /> == Dockies (Dir) ==<br /> <br /> == Ghostscript (Dir) ==<br /> <br /> == GraphicDump ==<br /> <br /> == HDBackup ==<br /> <br /> Note: Not yet released as of May 2014.<br /> <br /> == IconEdit ==<br /> <br /> == InitPrinter ==<br /> <br /> == Installation Utility ==<br /> <br /> == Installer ==<br /> <br /> == InstallExtras (Dir) ==<br /> <br /> == KeyShow ==<br /> <br /> == LogViewer ==<br /> <br /> == MEmacs ==<br /> <br /> == More ==<br /> <br /> == [[MultiView]] ==<br /> <br /> [[MultiView]] is a multipurpose viewer utility. It will display all files for which a datatype is installed. Multiview is capable of displaying different files such as text, pictures, sound and animations.<br /> It can be controlled by a GUI, command line arguments and an AREXX interface.<br /> <br /> == NotePad ==<br /> <br /> == PartitionWizard ==<br /> <br /> == PlayCD ==<br /> <br /> == ppp_connector, ppp_dialer, ppp_sample ==<br /> <br /> == PrefsObjectsEditor ==<br /> <br /> == PrintFiles ==<br /> <br /> == RawDisk ==<br /> <br /> == SGrab (Dir) ==<br /> <br /> == ShowConfig ==<br /> <br /> == UnArc ==<br /> <br /> == USBInspector ==</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=Wiki_Author_Credits&diff=7658 Wiki Author Credits 2014-05-04T16:39:41Z <p>Philippe Ferrucci: </p> <hr /> <div>The following is a list of known contributors to this wiki:<br /> * Adam Levin<br /> * Alexandre Balaban<br /> * [http://amigaak.org.nz/ Amiga Auckland]<br /> * Andy Finkel<br /> * Bart Whitebook<br /> * Bill Borsari<br /> * Bill Koester<br /> * Bob Burns<br /> * Bob Pariseau<br /> * Bruce Barrett<br /> * Bryce Nesbitt<br /> * Carl Sassenrath<br /> * Carolyn Scheppner<br /> * Chris Green<br /> * Chris Ludwig<br /> * Chris Raymond<br /> * Dale Luck<br /> * Dan Baker<br /> * Daniel Jedlicka<br /> * Darius Taghavy<br /> * Darren Greenwald<br /> * Dave Berezowski<br /> * Dave Lucas<br /> * David Junod<br /> * David Miller<br /> * Don Cox<br /> * Eric Cotton<br /> * Ewout Walraven<br /> * Frank Bunton, for his [http://aminet.net/package/docs/help/adosbegin AmigaDOS guide]<br /> * Hans-Joerg Frieden<br /> * James Jacobs<br /> * Jerry Hartzler<br /> * Jez San<br /> * Jim Mackraz<br /> * Joe Katz<br /> * John Orr<br /> * John Wiederhirn<br /> * Karl Churchill<br /> * Ken Farinsky<br /> * Kevin Klop<br /> * Larry Hildenbrand<br /> * Leo Schwab<br /> * [https://sites.google.com/site/takeaprogrammertolunch/ Lyle Hazelwood]<br /> * Mark Barton<br /> * Mark Ricci<br /> * [http://wandel.ca/ Markus Wandel]<br /> * Martin Taillefer<br /> * Michael Sinz<br /> * Nancy Rains<br /> * Neil Kafferkey<br /> * Neil Katin<br /> * Olaf Barthel<br /> * Paul Higginbottom<br /> * Paul Sadlik<br /> * Peter Cherna<br /> * Philippe Ferrucci<br /> * R.J. Mical<br /> * Randell Jesup<br /> * Ray Brand<br /> * Rob Peck<br /> * Rob Wyesham<br /> * Roman Kargin<br /> * Sam Dicker<br /> * Simon Archer<br /> * Spencer Shanson<br /> * Stan Shepard<br /> * Steve Beats<br /> * [http://www.solie.ca Steven Solie]<br /> * Stuart Ferguson<br /> * Susan Deyl<br /> * Thomas Frieden<br /> * Tom Pohorsky<br /> * Tom Rokicki</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=Utilities&diff=7657 Utilities 2014-05-04T16:26:22Z <p>Philippe Ferrucci: Created page with &quot;= Introduction = Below is the list of what is included in a default AmigaOS installation. You can find either programs or a group of &quot;sub-programs&quot; that another program needs...&quot;</p> <hr /> <div>= Introduction =<br /> <br /> Below is the list of what is included in a default AmigaOS installation. You can find either programs or a group of &quot;sub-programs&quot; that another program needs. For your convenience they are marked with a &quot;(Dir)&quot; if they represent a directory.<br /> <br /> = AmigaOS SYS:Utilities =<br /> <br /> == AmiGS (Dir) ==<br /> <br /> == AmiPDF (Dir) ==<br /> <br /> == Blankers (Dir) ==<br /> <br /> == bru ==<br /> <br /> == Calculator ==<br /> <br /> == CatComp ==<br /> <br /> == Clock ==<br /> <br /> == Commodities (Dir) ==<br /> <br /> == Dockies (Dir) ==<br /> <br /> == Ghostscript (Dir) ==<br /> <br /> == GraphicDump ==<br /> <br /> == HDBackup ==<br /> <br /> Note: Not yet released as of May 2014.<br /> <br /> == IconEdit ==<br /> <br /> == InitPrinter ==<br /> <br /> == Installation Utility ==<br /> <br /> == Installer ==<br /> <br /> == InstallExtras (Dir) ==<br /> <br /> == KeyShow ==<br /> <br /> == LogViewer ==<br /> <br /> == MEmacs ==<br /> <br /> == More ==<br /> <br /> == [[MultiView]] ==<br /> <br /> == NotePad ==<br /> <br /> == PartitionWizard ==<br /> <br /> == PlayCD ==<br /> <br /> == ppp_connector, ppp_dialer, ppp_sample ==<br /> <br /> == PrefsObjectsEditor ==<br /> <br /> == PrintFiles ==<br /> <br /> == RawDisk ==<br /> <br /> == SGrab (Dir) ==<br /> <br /> == ShowConfig ==<br /> <br /> == UnArc ==<br /> <br /> == USBInspector ==</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=UserDoc:Introduction_to_AmigaOS&diff=7656 UserDoc:Introduction to AmigaOS 2014-05-04T14:48:32Z <p>Philippe Ferrucci: /* AmigaOS Utilities */</p> <hr /> <div><br /> Like any modern personal computer system, AmigaOS presents a graphic interface and relies on common peripherals to let the user control their system. <br /> Beyond most systems, AmigaOS provides more flexibility and options in how the user can approach, configure and use their Amiga computer.<br /> <br /> In this page we will describe the details of AmigaOS graphic user interface (GUI) - how screens, windows and gadgets are presented and how you can use them.<br /> We will also describe the various means by which the user can control and operate AmigaOS. In additional pages, you can read about [[UserDoc:How AmigaOS Works|how AmigaOS works]] and what its components are.<br /> <br /> == AmigaOS Input - Point, Click and Type ==<br /> <br /> There are two common ways you can use and control your AmigaOS system - by mouse and keyboard. <br /> <br /> But AmigaOS also lets you control your system by other input devices (like touchscreens or voice recognition) depending on drivers and devices connected. Depending on software installed, AmigaOS can also be remotely controlled by networked protocols (like VNC and Synergy). Finally, AmigaOS can be controlled internal scripts set up by the User.<br /> <br /> === Using the mouse ===<br /> <br /> [[File:Style2.5.png|frame|right]]<br /> <br /> Typically in AmigaOS, you use a mouse to act on graphic elements (like &quot;gadgets&quot;, &quot;icons&quot; or webpage &quot;links&quot;). By default, AmigaOS expects and supports mice or trackball pointing devices with at least two buttons. The left mouse button is used to &quot;left-click&quot; on graphic objects, to select them or operate them. The right mouse button is used to &quot;right-click&quot; and display the menus of the current application.<br /> <br /> Optionally, one can use a mouse or trackball device with three (a &quot;middle&quot; button) and four buttons. With such devices, the functionality of the additional buttons can vary by application or environment. These functionalities can typically be configured by the user in specific applications or within AmigaOS (globally).<br /> <br /> Furthermore, scroll wheels are supported by AmigaOS in a context-based fashion. If the current application's window is scrollable, the scrollwheel will act on that area. If the mouse pointer is positioned over a specifically scrollable gadget, the scrollwheel will affect that gadget.<br /> <br /> In some applications and environments, you can also &quot;double-click&quot; (click twice, quickly) with the left button on an object to engage them. In the Workbench file manager, a single mouse click will only &quot;select&quot; an icon, whereas a double-click will open drawer/directory, run an application or open a file in an associated program.<br /> <br /> Beside &quot;clicking&quot; - pressing down and releasing a mouse button at a specific location - you can also perform what is known as &quot;dragging&quot;, which means clicking down and then moving the mouse around before releasing the mouse button. This is typically always done with the left mouse button and is done to select objects (draw a box around them), to adjust a control slider or to resize a window.<br /> <br /> &lt;br style=&quot;clear: both&quot; /&gt; <br /> <br /> === Using the keyboard ===<br /> <br /> Of course the keyboard is used to enter text into text editing areas. But your keyboard can do so much more with its special &quot;qualifier&quot; keys and AmigaOS.<br /> <br /> The most common example of a qualifier key is the &quot;Shift&quot; key which causes typed text to be made upper-case or capitalized. There are more qualifier keys on most keyboards, here is a list of all of them:<br /> * '''the Shift keys''' - the common key that causes your text to be capitalized.<br /> * '''The &quot;Alternate&quot; keys''' - the &quot;Alt&quot; keys typically to the bottom right and left of the keyboard.<br /> * '''the &quot;Control&quot; keys''' - the &quot;Ctrl&quot; keys also to the bottom right and left of the keyboard.<br /> * '''the &quot;Amiga&quot; keys''' - special &quot;A&quot; keys on the right and left side of the space bar. Besides being unique to AmigaOS, the right and left Amiga keys always mean different things (unlike the rest of the qualifier keys, most of the time). If you have a non-AmigaOS keyboard, the &quot;Windows&quot; or MacOS &quot;Command&quot; keys function as &quot;Amiga&quot; keys.<br /> ** '''the Right Amiga key''' - is used for &quot;short cuts&quot; within your current application.<br /> ** '''the Left Amiga key''' - is used for &quot;short cuts&quot; that are globally active anytime and anywhere in your AmigaOS system.<br /> While all of these qualifier keys don't usually do anything on their own, when you press and hold one or more of these keys down while pressing regular keys, they can change what you type (capitalizing or making alternate characters) or become powerful &quot;short-cuts&quot; within your applications or throughout your entire AmigaOS system.<br /> <br /> The most famous short-cuts are the '''copy''', '''cut''' and '''paste''' operations that you can perform on selected text:<br /> * the '''Right-Amiga C''' short-cut copies any selected text or content to the Clipboard.<br /> * the '''Right-Amiga X''' short-cut &quot;cuts&quot; any selected text or content to the Clipboard.<br /> * the '''Right-Amiga V''' short-cut &quot;pastes&quot; any text or content from the Clipboard into your application (at the current cursor location).<br /> <br /> == The AmigaOS GUI - Intuition ==<br /> <br /> When AmigaOS has started, you will typically see the Workbench file manager. This is the start of your experience with the AmigaOS GUI and it's most basic elements: a screen with menus and windows containing icons and &quot;gagdets&quot;. These components are the basic building blocks of virtually all AmigaOS &amp; application interfaces.<br /> <br /> As with most things in AmigaOS, almost all of the following components can also be almost infinitely reconfigured, adjusted and graphically varied by the user. In the AmigaOS &quot;Preferences&quot; drawer, the &quot;GUI&quot;, &quot;ASL&quot;, &quot;Locale&quot;, &quot;Font&quot;, &quot;Palette&quot;, &quot;Poiner&quot;, &quot;PopUpMenu&quot;, &quot;Screens&quot;, &quot;Workbench&quot; and &quot;WBPattern&quot; preferences editors easily allow a user to reconfigure the GUI of their Amiga in drammatic ways.<br /> <br /> AmigaOS also supports the use of alternate GUI systems in parallel with the default &quot;Intuition&quot; (aka &quot;Reaction&quot;) GUI system. By default AmigaOS also comes with the &quot;Magic User Interface system (&quot;MUI&quot;, a variant of the basic AmigaOS GUI system. More than Intuition, MUI can be reconfigured even more widely using its own MUI configuration app. <br /> <br /> Additionally, AmigaOS can use a number of third-party &quot;cross-platform&quot; GUI systems: &quot;AmiCygnix&quot; GUI system - a native X11 GUI implementation for AmigaOS - and a native port of the &quot;Qt&quot; GUI system. With either of these systems, it is possible to run ported applications compiled for AmigaOS, but running with these cross-platform GUI systems.<br /> <br /> To start with, we will explore the elements that make up the AmigaOS GUI system.<br /> <br /> === Screens ===<br /> <br /> As start-up, the Workbench will be running on its &quot;Workbench Screen&quot;. This will be the default location where most other application windows will also appear when started.<br /> <br /> Typically an AmigaOS screen will have a &quot;title bar&quot; across the top with a graphical &quot;depth gadget&quot; at the right end. In the case of the Workbench screen,<br /> there will be an AmigaOS &quot;boing ball&quot; at the left end and the title bar will display certain system information (OS version, memory availability, etc.). Within the screen, the Workbench and any other applications can open windows, display icons and other GUI devices. If you right-click over the title bar, it becomes a &quot;Menu Bar&quot;, showing you the control menus that are available for that application.<br /> <br /> In many cases, other applications may open screens in addition to the Workbench screen. The &quot;depth gadget&quot; at the right end of each screen's title bar allows you to click from screen from screen. Besides clicking on the screen's depth gadet, AmigaOS also lets the user see other screens behind the front screen by &quot;dragging' down on the screen title bar.<br /> <br /> The characteristics of the Workbench screen such as resolution and color depth can be configured in the &quot;Screenmode&quot; preferences editor. Other screens can be either be configured in the &quot;Screens&quot; preferences editor or from within individual applications. Typically, AmigaOS applications also give the user the choice of whether application runs on their own screens or the &quot;public&quot; Workbench screen.<br /> <br /> === Windows ===<br /> Windows are graphic containers that appear within AmigaOS screens. Windows can be created by any number of different applications - the Workbench, Shell sessions or applications. Outside of the Workbench file manager, each window usually reflects each individual running application. In some cases, one application may open multiple documents in separate windows or additional &quot;requester&quot; windows might appear for an application.<br /> <br /> [[File:LibFig4-1.png]]<br /> <br /> Almost all windows of AmigaOS will have these common elements:<br /> * '''Borders''' - A border around the window's contents. Holding the Shift+Left-Amiga keys down while dragging any border will drag the window around. <br /> * '''Title bar''' - A thicker top border that typically contains a name of the application or it's contents. The area of the title bar acts as a &quot;drag bar&quot; which you can use to drag the window around the screen.<br /> * '''Depth gadget''' - The right-most gadget in the top title bar that either pulls the window to front (if it isn't frontmost) or pushes it to the back (if it's in front). Holding down the Shift key while clicking this gagdet pushes the window to the back.<br /> <br /> In AmigaOS, windows may also optionally have these additional features and elements:<br /> * '''Close gadget''' - The left-most gadget in the title bar that closes the window.<br /> * '''Scroll bar(s) and arrows''' - If the contents of the window can be scrolled in vertically and/or horizontally, there will be a scroll bar with arrow scroll buttons. These scroll bars can also be used if the mouse pointer is over a scroll bar and the mouse scroll wheel is used.<br /> * '''Zoom gadget''' - the second gadget from the right-most of the title bar which switches the window between two sizes. Holding down the Shift key while clicking this gadget will make it fill the screen.<br /> * '''Iconification gadget''' - left-most of the right-hand gadgets in the title bar which causes the window to disappear into an icon on the Workbench background - thus &quot;Iconifying&quot; the window or application.<br /> * '''Sizing gadget''' - In the case of windows that can be resized, this is the gadget in the bottom right corner of the window that you can drag to resize the window.<br /> <br /> Each AmigaOS application can use almost infinite combinations of these features in the make up of their windows.<br /> <br /> === Menus ===<br /> <br /> [[File:LibFig2-4.png|frame|right]]<br /> Menus are lists of items that will allow you to see and use what commands are available in an application. The Workbench uses menus you can use to perform actions on the Workbench and its contents. Menus typically provide many more functions and commands than can be presented to the user than just graphic buttons, etc. within an application's window, as a result they are a primary way most applications are used.<br /> <br /> In AmigaOS menus can always be found for the current application by moving the mouse to the top of the screen and right-clicking. The screen title bar will become a menu bar and will show the names of all the current application's menus. <br /> <br /> By dragging with the right mouse button, each menu will display its &quot;menu items&quot;. Each of those menu items corresponds to a command or setting. In some cases you will find a &quot;check box&quot; on a menu item which you can click on to toggle a setting. In other cases, you will find that menu items have a little arrow head that indicates that item actually has a &quot;sub-menu&quot; - a menu within a menu. Menus ending with ellipses (&quot;...&quot;) indicate that menu item will open a window that can be cancelled without commiting any command. For those menu items that might be deactivated (they may not apply at the moment), they will be &quot;greyed-out&quot;.<br /> <br /> The labels of many menu items will also include a letter or two with an &quot;A&quot; at the right edge. This indicates what the keyboard Right-Amiga &quot;short cut&quot; is the equivalent of using that menu item within that application. In the above screen shot, you can see that pressing the two keys - &quot;Right-Amiga&quot; and &quot;N&quot; - would do the same as that menu item - to create a new drawer.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> <br /> ====Consistent Organization====<br /> For the sake of consistency (when applicable), the first two AmigaOS menus of any application are typically organized with the following hierarchy and use these keyboard equivalents:<br /> <br /> {| border=&quot;0&quot;<br /> |'''First Menu:'''<br /> ----<br /> || || Keyboard equivalent: || '''Second Menu:'''<br /> ----<br /> || || Keyboard equivalent:<br /> |-<br /> |'''PROJECT'''<br /> ----<br /> || || ||'''EDIT'''<br /> ----<br /> || <br /> |-<br /> |'''New'''|| = Create new project in application.||Right-Amiga N||'''Cut'''|| = Cut the selected content into the Clipboard.||Right-Amiga X<br /> |-<br /> |'''Open...'''|| = Open the file containing a project.||Right-Amiga O||'''Copy'''|| = Copy the selected content into the Clipboard.||Right-Amiga C<br /> |-<br /> |'''Save'''|| = Save the project to it's current file name.||Right-Amiga S||'''Paste'''|| = Paste the Clipboard contents into the project (at the current location).||Right-Amiga V<br /> |-<br /> |'''Save As...'''|| = Save the project to a file of a new name.|| ||'''Undo'''|| = Undo the last change to current project.||Right-Amiga Z<br /> |-<br /> |'''Print'''|| = Print the current project.||Right-Amiga P||'''Redo'''|| = Restore the last change &quot;undone&quot; in the current project.|| <br /> |-<br /> |'''Close'''|| = Close the project.|| || || || <br /> |-<br /> |'''Quit'''|| = Quit the application.||Right-Amiga Q|| <br /> |}<br /> <br /> ====Menu Variations====<br /> AmigaOS also includes a couple additional ways menus can be can serve the user:<br /> <br /> =====Pop-Up Menus=====<br /> <br /> [[File:OS4-WBPopUpMenu.jpg|frame|right]]<br /> In the GUI preferences editor you can configure menus to &quot;pop-up&quot; under the mouse pointer whenever you right-click the mouse. This means you do not need to move the mouse to the top of the screen to use the menus. There are also options for making menus &quot;sticky&quot;, meaning that you don't need to drag the mouse to navigate the menus, but rather just right click and the menus stay open till you make a selection or click away.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> <br /> =====Context Menus=====<br /> <br /> [[File:OS4-WBContextMenu.jpg|frame|right]]<br /> The Workbench (with a utility added by default) and many applications provide &quot;contextural menus&quot;. This means that you can put your mouse pointer over elements and right-click to pop-up a menu of things that are specific to the item you clicked over. In the case of the Workbench (with the Context Menus utility), right clicking on a file will pop-up a menu of things that could be done with that file, like deleting it.<br /> <br /> All of these features provide both a simple means of using many functions within an application and at the same time allowing the user to configure a very efficient user interface that responds to nearly every whim.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> <br /> === Icons ===<br /> <br /> ==== Description ====<br /> Icons are small images which can represent a disk, a directory, an application file or data file. Icons are primarilly used within the AmigaOS Workbench environment to represent all the file system objects the user can manipulate. With these icons it is possible to select files, open them, delete them or move them around within the Workbench. Applications may also make more limited use of icons to represent file system objects or may be used as imagery in an &quot;icon bar&quot; of buttons that can be clicked to perform various actions represented by icon imagery, like the Clock above.<br /> <br /> {|style=&quot;text-align: center;&quot;<br /> |[[File:LibDiskIcon.png|frame|left|100px|Drive icon]] [[File:Icons.png|frame|right|Directory with sub-directory, data and application file icons]]<br /> |}<br /> <br /> AmigaOS also uses different icon imagery to indicate various types of icons - drives, directories, files and applications. Drive or partition icons look like little hard drives. <br /> A directory icon will look like a cabinet &amp; drawer whereas a file icon will be designed to give a clue about the file content.<br /> Data files are normally shown with a &quot;page&quot; motif and some graphics or text to reflect the file type.<br /> Application files typically have the most free-form graphics that reflect their purpose, name or developer.<br /> <br /> The user can also edit the icon imagery using the icon editor, change how icons react to being double-clicked and adjust parameters stored within the icon file that affect how the represented file will be used.<br /> <br /> Many applications and all AmigaOS file requesters allow Workbench icons to be &quot;dragged and dropped&quot; into the application or requester windows and the associated file will be recognized by the application, if possible.<br /> <br /> ==== Icon states ====<br /> <br /> Icons can look different not only because of their image but also depending on their state. <br /> <br /> As you can see in the directory example, the 2 top left icons appear semi-transparent. This subtle difference reflects whether the file or directory has an associated icon file with it. In AmigaOS, any directory or file can have such an icon file that stores a unique icon image, unique program settings or specific settings for that file or directory. That information can be adjusted within the Workbench and is automatically stored in a companion file with the same name, but with an added '''.info''' suffix. <br /> <br /> While many files &amp; directories and most applications have such &quot;.info files&quot; with them, they are not required and the Workbench can be set to show you &quot;default icons&quot; (based on the file types, etc.) so you can manipulate the corresponding objects. Of course, AmigaOS can also be configured on a directory-by-directory basis to only show files that have associated &quot;.info&quot; files.<br /> <br /> In the same picture, the 2 top right directory icons also look slightly different. While the '''Utilities selected''' and the '''Utilities unselected''' are the same icon, their image is a bit different. The drawer of the first one is slightly opened and there is a &quot;glow&quot; effect arround the first icon. These two visual clues show you the first directory icon has been selected by the user whereas the second one is not.<br /> <br /> ==== App Icons ====<br /> <br /> Many applications provide the option to be &quot;iconified&quot; either by clicking on an iconification gadget in their window title bars or by menu item. In those events, the application's window will disappear and an &quot;app icon&quot; will appear on the background of the Workbench screen. Double-clicking on the app icon will cause the icon to disappear and the application's window to reappear. Even while the application is iconified, it does continue to run and perform whatever the user may have it doing.<br /> <br /> Some applications may also place an app icon on the Workbench background even while the application is open to allow the user to be able to drop other file icons on the app icon and have them be used by the application.<br /> <br /> === Graphic gadgets ===<br /> Within AmigaOS and application windows, there can be any number of graphic devices meant to be operated by your mouse with clicks and drags - these are known as &quot;gagdets&quot;. In most cases, the gagdets are simple analogs of real world objects - like buttons you press with your finger, forms you fill out with a pencil or tabs on folders.<br /> <br /> [[File:LibFig5-1.png]]<br /> <br /> ==== Buttons ====<br /> <br /> [[File:OS4-Buttons.jpg|frame|right]]<br /> Buttons (or &quot;Boolean gadgets&quot;) are some of the most common GUI objects. With a simple left-click of your mouse button, they are used to perform actions, set configurations or indicate choices. <br /> <br /> In AmigaOS, clicking &quot;down&quot; on a button typically causes the button to be rendered differently, to reflect that it has been &quot;pressed&quot;. Engaging the button is not actually recognized until you let go with the mouse button over the graphic gadget. This means that while the gadget has been clicked down, you always have the option of moving the mouse off the button gadget and then letting go and it will be as though the button had never been &quot;pressed&quot; or clicked on.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> ==== Text gadgets ====<br /> <br /> [[File:OS4-StringGadgets.jpg|frame|right]]<br /> A text gadget (or &quot;String gadget&quot;) works like a space in a paper form to be filled out - left click in the gadget, you will see a cursor appear and you can type your answer.<br /> Once you've finished typing your infrormation, you can either press the enter, carriage-return or tab keys for your entry to be recognized.<br /> <br /> Text or string gadgets can also come in a number of variants for specific uses. Some can limit input to be numeric only (and may have adjacent buttons to increment or decrement the value). Some string gadgets may be specifically be meant for file or directory names and they have adjacent gagdets that will bring up a file requester to set the value. Many times a numeric gadget is paired with a slider gadget (as in the example above), where the value can either be set by typing in the gadget or by using the slider.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> ==== Sliders &amp; Scroll Bars ====<br /> <br /> [[File:OS4-SliderGadgets.jpg|frame|right]]<br /> Slider gadgets work like controls many of have seen on their stereo systems - left-click and drag on the gadget &quot;knob&quot; to move it back and forth to set a value. A more sophisticated variant of the slider is the &quot;scroll bar&quot; that has a variably sized scroll bar contained in a scroll box that lets you see what proportion of the active range is visible or active.<br /> <br /> With all slider and scroller gadgets AmigaOS also lets you click in the area to either side of the knob or slider to adjust the setting. In the case of sliders, the value will typically move by a fixed amount (+/- 1 or some suitable increment). In the case of scroll bars, clicking in the scroll box on either side of the scroll bar will cause the value to move in increments of the scroll bar size. Scroll bars also come with &quot;scroll arrows&quot; at the end of the scroll box that allow for finer movement of the scroll bar.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> ==== Cycle gadgets ====<br /> <br /> [[File:OS4-CycleGadgets.jpg|frame|right]]<br /> Cycle gagdets are a variant on buttons that let you select from a number of specific choices. You can either click on the majority of the gadget to pop-up a list of choices to select from or click on the circular arrow to cycle between the list of choices. Cycle gagdets rarely cause actions to occur, they just adjust some setting or configuration.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> ==== Check Box &amp; Radio Button gadgets ====<br /> <br /> [[File:OS4-CheckRadioGadgets.jpg|frame|right]]<br /> Another variant of buttons, check boxes can be clicked to set on/off or yes/no conditions with a checkmark, just like a check box in a paper form. Radio buttons are another variant where two or more round buttons are presented in a set and only one of the set can be clicked and activated, like the buttons on a stereo system.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> ==== Tabs ====<br /> <br /> [[File:OS4-Tabs.jpg|frame|right]]<br /> Tabs are a graphical gadget that is used in combination with a &quot;pages&quot; or sets of gadgets and/or information, and you can click on the &quot;tabs&quot; to switch between the pages - like you might in a real notebook with tabbed pages. This provides a efficient way to present more information and settings in a compact interface.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> ====Requesters====<br /> <br /> [[File:LibFig2-5.png|frame|right]]<br /> As one uses AmigaOS and it's applications, from time to time a &quot;Requester&quot; window may appear to ask the user a question - basically windows with gadgets in them. Such requesters can appear to confirm an action, obtain more information, make a selection or configuration. Typically a series of buttons across the bottom of the window will dispatch the requester, with the bottom-left button gadget indicating some affirmative choice and the bottom-right button gagdet cancelling the requester (performing no action or change).<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> <br /> ====Keyboard Operation of Gadgets====<br /> As with so many things, AmigaOS and its applications provide a secondary way to operate many of these gadgets - by keyboard. If a window contains text gadgets, pressing your keyboard's TAB key will activate the text gadgets in sequence (a cursor will appear in each so you can type &amp; edit). Each press of the TAB key will cycle to the next gadget and pressing SHIFT + TAB will cycle through the gadgets in reverse order.<br /> <br /> You may have noticed in many of the above sample images that many of the gagdets or their adjacent &quot;label&quot; texts contain a single underlined character. This is a sign that pressing that key on your keyboard will activate that gadget. Each gadget can then be operated by your keyboard - just like clicking on a button, clicking on a tab, setting a text or numeric value, etc. Of course, if you are in the midst of typing in a text gadget, then things you type will go into that gadget instead of operating other gagdets.<br /> <br /> == Finding Files in AmigaOS ==<br /> <br /> [[File:OS4-ASLReq.jpg|frame|right]]<br /> AmigaOS provides a consistent method for navigating your file system and finding your files from within your apps - the &quot;ASL file requester&quot;. It is used by everything in AmigaOS and most third party applications. It is the window (or &quot;requester&quot;) that appears when you want to open or save files.<br /> <br /> As you can see, the ASL file requester presents the files in a given location in your file systems (a directory or &quot;drawer&quot;) and shows their size, date of creation or last modification and any comments attached to the file. The above example shows the same directory as appeared above in this page.<br /> <br /> At the bottom corners of the window are buttons to accept the selection (&quot;OK&quot;) or cancel the requester. Between those are buttons to view all the drives &amp; partitions on your system (&quot;Volumes&quot;) or to move to the &quot;Parent&quot; of the current directory.<br /> <br /> Also at the bottom of the window you will see three text gadgets. The first of these is optional and allows you to filter what is shown in the file list - it is now shown filtering out any file with a &quot;.info&quot; suffix (those are AmigaOS icon files). The next two lines reflect the current directory path name and the currently selected file name (also selected in the file list above). In the case of saving files, you would type any name you wanted in the bottom text field to create a new file. Clicking on the titles of the file list will let you sort the file list.<br /> <br /> Of course this being AmigaOS, the ASL requester has its own &quot;preferences editor&quot; that lets you set how the requester appears, is sorted by default and a number of mouse button short-cuts.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> <br /> == Controlling AmigaOS - Which Way? ==<br /> <br /> AmigaOS provides a number of parallel ways that the user can control and put their Amigas to use. The easiest and most common method is to use the AmigaOS graphic icons, windows and mouse interface - the &quot;Workbench&quot; - using all the GUI elements described above. But AmigaOS also provides a more traditional or &quot;old fashioned&quot; method called a command line interface (the &quot;CLI&quot; or &quot;Shell&quot;), where the user can type text commands and interact using a text interface. AmigaOS also provides a unique means of &quot;interprocess communications&quot; where user can have many applications and parts of the OS &quot;talk&quot; to each other. <br /> <br /> === The Workbench &amp; Intuition ===<br /> <br /> As we described above, AmigaOS provides the &quot;Workbench&quot;, a straightforward, efficient and easy graphical means to start applications, manage your computer and all your files. Files and programs are represented with icons, generally known as &quot;Projects&quot; and &quot;Tools&quot;. They can be stored in any arrangement of directories (&quot;Drawers&quot;). You double-click on a program icon and it will open in a Intuition GUI window on your Workbench screen. <br /> <br /> Please see the section about the AmigaOS [http://wiki.amigaos.net/index.php/UserDoc:Workbench Workbench] to learn these concepts:<br /> <br /> * What is the Workbench<br /> * Workbench menus<br /> * Keyboard control<br /> * Workbench requesters<br /> * Configuration<br /> * Workbench help<br /> <br /> === The Shell &amp; DOS Commands ===<br /> <br /> [[File:OS4-Window-Shell.jpg|frame|right]]<br /> The AmigaOS Shell can be opened by double-clicking the &quot;Shell&quot; icon in the AmigaOS &quot;System&quot; drawer. The Shell is a text based interface that allows you to perform most of the same operations as the Workbench - to run and interact with application programs, manage files and control your Amiga computer. AmigaOS also comes with dozens of standard &quot;DOS commands&quot; (programs purely meant for Shell usage). Simply enter the name of a program or command (like &quot;dir&quot;) and press Enter, the command or program will run and it will print its results in the Shell window. While considered old fashioned, many users find the Shell to still be the most efficient way to perform many tasks on the Amigas.<br /> <br /> Please see the section on the [[UserDoc:Shell|AmigaOS Shell]] to learn more.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> <br /> === Scripts &amp; Messages ===<br /> <br /> Scripts are simple text files that contain a list of commands written in a variety of languages: the AmigaDOS, Arexx and Python languages are provided with AmigaOS - there are many others. Each of these language has its strengths. You'll have to learn the one that suits what you want to do. You can create a script using a text editor. You can run such script from the Workbench or from the shell (or from any other script). By using ARexx ports provided by AmigaOS components (the Workbench or Multiview, for example) or third-party applications, scripts can be used to make your computer perform a wide variety of actions.<br /> <br /> == AmigaOS System Tools ==<br /> AmigaOS comes with a variety of programs to help in the preparation of your computer. These include tools for:<br /> <br /> * Drive preparation (Media Toolbox, Format, Format DCRW &amp; Mounter).<br /> * Font Handling (TypeManager &amp; FixFonts).<br /> * Script Languages (RexxMast and Python).<br /> * The Shell.<br /> * Miscellaneous Utilities (Find, Help, Grim Reaper &amp; Ringhio Server).<br /> <br /> == AmigaOS Utilities ==<br /> AmigaOS comes with a selection of utilities to assist the user, including:<br /> <br /> * Commodities.<br /> * Editors (Notepad, MEmacs, PrefsObjectEditor &amp; IconEdit).<br /> * Postscript oriented apps (AmiPDF, AmiGS &amp; Ghostscript).<br /> * Disk apps (PartitionWizard &amp; RawDisk).<br /> * Screenblankers.<br /> * AmiDock and Dockies.<br /> * The Unarc dearchiver.<br /> * PlayCD.<br /> * Several &quot;sub-programs&quot; that are used by other system utilities (blankers, dockies)<br /> * Miscellaneous apps (Clock, printing apps, KeyShow, install apps, etc.).<br /> <br /> Read [[Utilities|here]] to find all of them explained further.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=UserDoc:How_AmigaOS_Works&diff=7655 UserDoc:How AmigaOS Works 2014-05-04T14:45:11Z <p>Philippe Ferrucci: /* System components */</p> <hr /> <div>As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.<br /> <br /> In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.<br /> <br /> = Introduction =<br /> <br /> AmigaOS is made of different components which are either mandatory i.e. AmigaOS will not work without them or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.<br /> <br /> = The most important components =<br /> <br /> == Exec, the AmigaOS kernel ==<br /> <br /> Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible of running programs, dealing with computer memory, managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.<br /> <br /> It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.<br /> <br /> == AmigaDOS: the underlying system ==<br /> <br /> The word &quot;DOS&quot; was originally an acronym for &quot;Disk Operating System&quot;. Some say it should be &quot;Disk Based Operating System&quot; as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be &quot;Device Operating System&quot;.<br /> <br /> The whole AmigaDOS system includes things such as:<br /> <br /> * A set of commands that can be used in the Shell window and elsewhere.<br /> * A system for saving data to disk and retrieving it from disk.<br /> * A system for filing data on disks.<br /> * An interface for peripherals such as keyboards, monitors, printers, etc.<br /> * A method of running programs<br /> * A multitasking system for running more than one program at a time.<br /> * etc. etc. etc.<br /> <br /> Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.<br /> <br /> == The Graphics library ==<br /> <br /> The Graphics library handles every low level graphic operations like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.<br /> <br /> == Intuition ==<br /> <br /> The Intuition library is responsible for every graphical objects: windows, screens, gadgets, mouse pointers... It lays between any graphic program and the graphics library.<br /> <br /> == The Workbench ==<br /> <br /> The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.<br /> [[File:Wb.png|320px]]<br /> <br /> == The Shell ==<br /> <br /> While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.<br /> <br /> == ARexx - inter-program communication by scripting ==<br /> <br /> The ARexx scripting language can be used to operate the Workbench and the most important Amiga applications from a script containing ARexx commands. This is extremely useful to perform repetitive tasks or to do what the controlled application was not even design to do.<br /> After a learning curve, everybody can use ARexx as it is built in the system and the scripts can be executed immediately like any other tool.<br /> <br /> = How is my data stored? =<br /> == Files ==<br /> === Executable files ===<br /> Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.<br /> An example is a music player. When you start this executable, the player opens and you can start playing music files.<br /> <br /> AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The laters are executed inside an emulation that transcripts them into PowerPC code.<br /> <br /> ==== Scripts ====<br /> <br /> Scripts are text files containing a list of commands. So they are not strictly executables like ''binary code'' files but they can be executed by AmigaOS like if they were.<br /> This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.<br /> <br /> === Data files ===<br /> Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.<br /> <br /> == Directories/Drawers ==<br /> In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.<br /> Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.<br /> <br /> Note: directories are often called ''folders'' on other systems.<br /> <br /> == Disks, partitions and volumes ==<br /> === Disks ===<br /> Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.<br /> <br /> === Partitions ===<br /> A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.<br /> <br /> [[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]<br /> <br /> On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.<br /> <br /> === Volumes ===<br /> A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.<br /> <br /> = How to identify files/directories =<br /> <br /> == On the Workbench ==<br /> <br /> The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...<br /> <br /> In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.<br /> <br /> == In a shell ==<br /> <br /> In a shell you need to issue the command '''list''' to see if an object is a file or a directory.<br /> <br /> [[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]<br /> <br /> A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.<br /> <br /> Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.<br /> <br /> = All AmigaOS components =<br /> <br /> AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.<br /> <br /> == Kickstart modules ==<br /> <br /> These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is some kind of director handling the work of all other components.<br /> These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:<br /> <br /> === Mandatory modules ===<br /> <br /> The following modules are required in any AmigaOS system. Without one of these, the system will not start.<br /> <br /> * kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.<br /> * loader - this component handles the loading of all other kickstart modules<br /> * battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time<br /> * bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS<br /> * bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS<br /> * con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface<br /> * console.device.kmod - it opens a window and reads/writes text to and from that window<br /> * diskboot.kmod - handles the booting of AmigaOS from a supported disk<br /> * diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS<br /> * dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories<br /> * elf.library.kmod - handles the loading of executable programs<br /> * env-handler.kmod - handles the read/writes of environment variables<br /> * FileSystem.resource.kmod - handles the use of the different filesystems<br /> * gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...<br /> * gameport.device.kmod - handles the read/writes of game pads and joysticks<br /> * graphics.library.kmod - collection of functions used to draw graphic elements on the monitor<br /> * hunk.library.kmod - set of functions to read a data stream into memory<br /> * input.device.kmod - handles of input events like keyboard events or mouse clicks<br /> * intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)<br /> * layers.library.kmod - set of functions to be used to handle different layers in graphic operations<br /> * keyboard.device.kmod - driver for the keyboard<br /> * keymap.library.kmod - functions to handle different keymaps<br /> * newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )<br /> * nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage<br /> * nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers<br /> * PCIGraphics.card - driver that supports the use of different graphic cards<br /> * ram-handler.kmod - functions that handles the '''Ram disk:''' special disk<br /> * ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk<br /> * ramlib.kmod - loads disk based libraries and devices for exec.library<br /> * rtg.library - library of functions perform lowlevel graphic operations on graphic cards<br /> * shell.kmod - the AmigaOS command line interface<br /> * strap.kmod - module that handles booting on different disk devices<br /> * timer.device.kmod - driver to give access to timing functions<br /> <br /> === Filesystem support ===<br /> <br /> These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.<br /> <br /> * CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...<br /> * SmartFilesystem - allows to store data on partitions in SFS0 and SFS2<br /> * JXFileSystem - allows to create partitions in JXFS<br /> * FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts<br /> * diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules<br /> <br /> === Hardware drivers ===<br /> <br /> ==== Graphic cards drivers ====<br /> <br /> * 3dfxVoodoo.chip<br /> * 3DLabsPermedia2.chip<br /> * ATIRadeon.chip<br /> * RadeonHD.chip<br /> * siliconmotion502.chip<br /> <br /> ==== Disk drivers ====<br /> <br /> Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.<br /> <br /> * it8212ide.device.kmod<br /> * lsi53c8xx.device.kmod<br /> * sam460sata.device.kmod<br /> * sii3112ide.device.kmod<br /> * sii3512ide.device.kmod<br /> * sii3114ide.device.kmod<br /> * sii0680ide.device.kmod<br /> * sii3132ide.device.kmod<br /> <br /> ==== USB drivers ====<br /> <br /> * hub.usbfd<br /> * usbsys.device<br /> * usbresource.library<br /> * ehci.usbhcd<br /> * ohci.usbhcd<br /> * uhci.usbhcd<br /> * massstorage.usbfd<br /> <br /> ==== Other drivers ====<br /> <br /> * bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded<br /> * bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded<br /> * fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers<br /> * i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers<br /> * xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000<br /> <br /> === Misc modules ===<br /> <br /> * petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor<br /> <br /> == System components ==<br /> <br /> [[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]<br /> <br /> Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.<br /> Here is described a default AmigaOS installation.<br /> <br /> * C<br /> This directory contains AmigaDOS '''C'''ommands<br /> * Classes<br /> contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...<br /> * Devs<br /> contains definition for '''Dev'''ices<br /> * Emulation<br /> contains files used for the 68k emulation (though E-UAE)<br /> * Fonts<br /> contains various systems fonts<br /> * Internet<br /> contains a dialer to connect to Internet<br /> * Kickstart<br /> contains the kickstart modules<br /> * L<br /> contains hand'''l'''ers and filesystems<br /> * Libs<br /> contains dynamic '''Libr'''airies of functions<br /> * Locale<br /> contains all files used to localise the system (catalogs, keymaps...)<br /> * MUI<br /> contains the needed files for programs that use the MUI third party graphic interface<br /> * Prefs<br /> contains the preference programs used to customise AmigaOS<br /> * S<br /> contains the '''S'''cripts<br /> * SObjs<br /> contains .so shared object library files<br /> * Storage<br /> contains other optional files<br /> * System<br /> contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools<br /> * [[Utilities]]<br /> contains several programs you can use to achieve some tasks on AmigaOS<br /> <br /> = Motorola 680x0 Emulators =<br /> <br /> For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.<br /> <br /> In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be &quot;switched off&quot;.<br /> <br /> Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. &quot;Native&quot; PowerPC programs were rare, and every time a PowerPC program called the system, a so called &quot;context switch&quot; occurred between the 680x0 and PowerPC code, often causing a large performance penalty.<br /> <br /> The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor. <br /> <br /> == Two 680x0 Emulators ==<br /> <br /> In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low &quot;reaction time&quot;, and is ideal for time critical parts, such as interrupts.<br /> <br /> The other is Petunia, the &quot;JIT emulator&quot;. A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.<br /> <br /> Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, &quot;on the fly&quot;.<br /> <br /> This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.<br /> <br /> == Features ==<br /> <br /> Emulated opcodes:<br /> * all user and supervisor level opcodes of the Motorola 68040<br /> * all FPU opcodes of the Motorola 68881/68882 <br /> <br /> AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.<br /> <br /> At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.<br /> <br /> == Removing the JIT Emulator ==<br /> <br /> Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.<br /> <br /> If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.<br /> <br /> Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the &quot;Sys:Kickstart/Kicklayout&quot; file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like &quot;DefaultJIT&quot;, or &quot;DefaultNoJIT&quot;.<br /> <br /> == Configuring the Emulators ==<br /> <br /> Petunia cooperates with a so called &quot;black list&quot;. By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.<br /> <br /> If an executable needs to be added to the list, then it can be done by extending the file &quot;DEVS:applications.dos&quot; with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.<br /> <br /> Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.<br /> <br /> Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.<br /> <br /> For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list. <br /> <br /> = AmigaOS boot procedure =<br /> <br /> Basically a computer with AmigaOS does the following when the power button is pushed:<br /> <br /> * [[File:Uboot.jpg|200px]]<br /> the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.<br /> * depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.<br /> * [[File:SLB.png|200px]]<br /> the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.<br /> The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.<br /> * [[File:Kmods loading.png|200px]]<br /> the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module<br /> * '''Loader''' executes the kickstart modules (Exec, devices, libraries...)<br /> * AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor<br /> * the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume<br /> * the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.<br /> * the Workbench is started<br /> <br /> At this point the user can use his/her computer.<br /> <br /> = How to make a Bootable USB Memory Stick for AmigaOS 4.1 =<br /> <br /> By Julian Margetson (&quot;Spectre660&quot;)<br /> <br /> Prerequisites:<br /> * USB memory stick of 2 GB or less in size.<br /> * It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.<br /> * Plug the USB memory stick into a USB port on your machine.<br /> * Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.<br /> <br /> Procedure:<br /> # You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.<br /> # Make certain that you have selected usbdisk.device and not any other device.<br /> # Click on &quot;Start&quot;<br /> # You will see the usb mass storage unit connected in a list.<br /> # Make sure that the Unit type displayed for the USB memory stick is &quot;Removable hard disk&quot;<br /> # Select that Unit by clicking on it.<br /> # The first thing that you need to do is to install the RDB onto the USB Memory Stick.<br /> # Click on the &quot;Install&quot; button.<br /> # A window Labeled &quot;RDB/disk geometry editing&quot; comes up.<br /> ## Towards the bottom of the window is the &quot;AmigaOne boot code (SLB)&quot; section.<br /> ## Select the &quot;Install&quot; button .<br /> ## A file requester &quot;Select AmigaOne Boot Code&quot; now comes up with the Drawer choice defaulting to &quot;l:&quot;<br /> ## Select file &quot;slb_v2&quot;. <br /> ## Select Ok.<br /> ## You are now returned to the &quot;RDB/disk geometry editing window&quot;.<br /> ## Select &quot;Ok-accept changes&quot;.<br /> # You are now returned to the display showing the attached USB unit.<br /> # Select &quot;Edit partitions and Filesystems&quot;. You will now see the Window 'Editing partitions for disk&quot;<br /> # Select &quot;Add partition&quot;<br /> # This defaults to using the whole device as a single partition.<br /> # It is possible to use create more partitions but for this tutorial we will only use one.<br /> # You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the &quot;Name&quot; box.<br /> # Now make sure that the Boxes &quot;Automount&quot; and &quot;Bootable&quot; are selected and show the &quot;Tick mark&quot;.<br /> # You need to set &quot;Boot priority&quot; to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the &quot;+&quot; to the right of the &quot;boot priority&quot; box. Normally you can set the boot priority to 2 .<br /> # Next it is time to select the file system to use.<br /> # Select &quot;Select filesystem/edit details&quot;.<br /> # The Window &quot;Editing details for partition 'USB0'&quot; ,or whatever partition name you used, comes up.<br /> ## Select the file system that you are going to use by selecting the pull down menu under &quot;Filesystem chooser&quot;.<br /> ## Only filesystems SFS/00 or SFS/02 will work for a bootable device.<br /> ## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.<br /> ## Next select Blocksize from the &quot;Blocksize&quot; pull down menu. 512 is the correct size to use.<br /> ## Now Select &quot;Ok-accept changes&quot;.<br /> ## Your are now returned to the &quot;Edit partitions for disk&quot; window.<br /> ## Again select &quot;Ok-accept changes&quot;<br /> # You are now returned to the window showing the USB mass storage unit list.<br /> # Select &quot;Save to disk&quot;<br /> # A requester pops up with the options &quot;Yes, Save.&quot; or &quot;No!&quot;<br /> # Select the &quot;Yes, save.&quot; option.<br /> # You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.<br /> # This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.<br /> # Select &quot;Yes, reboot NOW!&quot;.<br /> # Once you have rebooted connect your USB Memory Stick to a USB port.<br /> # A disk icon &quot;USB0:Uninitialized&quot; (or whatever partition name you used) appears on Workbench.<br /> # You now need to format the device.<br /> # To format Select this Icon and go to the Workbench &quot;Icons&quot; menu .<br /> # Select &quot;Format Disk&quot;<br /> # You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.<br /> # You can use either a full Format or a Quick Format. Full Format may take a few minutes.<br /> # Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=UserDoc:How_AmigaOS_Works&diff=7654 UserDoc:How AmigaOS Works 2014-05-04T14:40:31Z <p>Philippe Ferrucci: /* System components */</p> <hr /> <div>As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.<br /> <br /> In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.<br /> <br /> = Introduction =<br /> <br /> AmigaOS is made of different components which are either mandatory i.e. AmigaOS will not work without them or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.<br /> <br /> = The most important components =<br /> <br /> == Exec, the AmigaOS kernel ==<br /> <br /> Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible of running programs, dealing with computer memory, managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.<br /> <br /> It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.<br /> <br /> == AmigaDOS: the underlying system ==<br /> <br /> The word &quot;DOS&quot; was originally an acronym for &quot;Disk Operating System&quot;. Some say it should be &quot;Disk Based Operating System&quot; as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be &quot;Device Operating System&quot;.<br /> <br /> The whole AmigaDOS system includes things such as:<br /> <br /> * A set of commands that can be used in the Shell window and elsewhere.<br /> * A system for saving data to disk and retrieving it from disk.<br /> * A system for filing data on disks.<br /> * An interface for peripherals such as keyboards, monitors, printers, etc.<br /> * A method of running programs<br /> * A multitasking system for running more than one program at a time.<br /> * etc. etc. etc.<br /> <br /> Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.<br /> <br /> == The Graphics library ==<br /> <br /> The Graphics library handles every low level graphic operations like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.<br /> <br /> == Intuition ==<br /> <br /> The Intuition library is responsible for every graphical objects: windows, screens, gadgets, mouse pointers... It lays between any graphic program and the graphics library.<br /> <br /> == The Workbench ==<br /> <br /> The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.<br /> [[File:Wb.png|320px]]<br /> <br /> == The Shell ==<br /> <br /> While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.<br /> <br /> == ARexx - inter-program communication by scripting ==<br /> <br /> The ARexx scripting language can be used to operate the Workbench and the most important Amiga applications from a script containing ARexx commands. This is extremely useful to perform repetitive tasks or to do what the controlled application was not even design to do.<br /> After a learning curve, everybody can use ARexx as it is built in the system and the scripts can be executed immediately like any other tool.<br /> <br /> = How is my data stored? =<br /> == Files ==<br /> === Executable files ===<br /> Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.<br /> An example is a music player. When you start this executable, the player opens and you can start playing music files.<br /> <br /> AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The laters are executed inside an emulation that transcripts them into PowerPC code.<br /> <br /> ==== Scripts ====<br /> <br /> Scripts are text files containing a list of commands. So they are not strictly executables like ''binary code'' files but they can be executed by AmigaOS like if they were.<br /> This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.<br /> <br /> === Data files ===<br /> Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.<br /> <br /> == Directories/Drawers ==<br /> In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.<br /> Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.<br /> <br /> Note: directories are often called ''folders'' on other systems.<br /> <br /> == Disks, partitions and volumes ==<br /> === Disks ===<br /> Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.<br /> <br /> === Partitions ===<br /> A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.<br /> <br /> [[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]<br /> <br /> On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.<br /> <br /> === Volumes ===<br /> A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.<br /> <br /> = How to identify files/directories =<br /> <br /> == On the Workbench ==<br /> <br /> The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...<br /> <br /> In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.<br /> <br /> == In a shell ==<br /> <br /> In a shell you need to issue the command '''list''' to see if an object is a file or a directory.<br /> <br /> [[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]<br /> <br /> A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.<br /> <br /> Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.<br /> <br /> = All AmigaOS components =<br /> <br /> AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.<br /> <br /> == Kickstart modules ==<br /> <br /> These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is some kind of director handling the work of all other components.<br /> These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:<br /> <br /> === Mandatory modules ===<br /> <br /> The following modules are required in any AmigaOS system. Without one of these, the system will not start.<br /> <br /> * kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.<br /> * loader - this component handles the loading of all other kickstart modules<br /> * battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time<br /> * bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS<br /> * bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS<br /> * con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface<br /> * console.device.kmod - it opens a window and reads/writes text to and from that window<br /> * diskboot.kmod - handles the booting of AmigaOS from a supported disk<br /> * diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS<br /> * dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories<br /> * elf.library.kmod - handles the loading of executable programs<br /> * env-handler.kmod - handles the read/writes of environment variables<br /> * FileSystem.resource.kmod - handles the use of the different filesystems<br /> * gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...<br /> * gameport.device.kmod - handles the read/writes of game pads and joysticks<br /> * graphics.library.kmod - collection of functions used to draw graphic elements on the monitor<br /> * hunk.library.kmod - set of functions to read a data stream into memory<br /> * input.device.kmod - handles of input events like keyboard events or mouse clicks<br /> * intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)<br /> * layers.library.kmod - set of functions to be used to handle different layers in graphic operations<br /> * keyboard.device.kmod - driver for the keyboard<br /> * keymap.library.kmod - functions to handle different keymaps<br /> * newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )<br /> * nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage<br /> * nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers<br /> * PCIGraphics.card - driver that supports the use of different graphic cards<br /> * ram-handler.kmod - functions that handles the '''Ram disk:''' special disk<br /> * ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk<br /> * ramlib.kmod - loads disk based libraries and devices for exec.library<br /> * rtg.library - library of functions perform lowlevel graphic operations on graphic cards<br /> * shell.kmod - the AmigaOS command line interface<br /> * strap.kmod - module that handles booting on different disk devices<br /> * timer.device.kmod - driver to give access to timing functions<br /> <br /> === Filesystem support ===<br /> <br /> These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.<br /> <br /> * CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...<br /> * SmartFilesystem - allows to store data on partitions in SFS0 and SFS2<br /> * JXFileSystem - allows to create partitions in JXFS<br /> * FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts<br /> * diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules<br /> <br /> === Hardware drivers ===<br /> <br /> ==== Graphic cards drivers ====<br /> <br /> * 3dfxVoodoo.chip<br /> * 3DLabsPermedia2.chip<br /> * ATIRadeon.chip<br /> * RadeonHD.chip<br /> * siliconmotion502.chip<br /> <br /> ==== Disk drivers ====<br /> <br /> Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.<br /> <br /> * it8212ide.device.kmod<br /> * lsi53c8xx.device.kmod<br /> * sam460sata.device.kmod<br /> * sii3112ide.device.kmod<br /> * sii3512ide.device.kmod<br /> * sii3114ide.device.kmod<br /> * sii0680ide.device.kmod<br /> * sii3132ide.device.kmod<br /> <br /> ==== USB drivers ====<br /> <br /> * hub.usbfd<br /> * usbsys.device<br /> * usbresource.library<br /> * ehci.usbhcd<br /> * ohci.usbhcd<br /> * uhci.usbhcd<br /> * massstorage.usbfd<br /> <br /> ==== Other drivers ====<br /> <br /> * bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded<br /> * bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded<br /> * fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers<br /> * i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers<br /> * xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000<br /> <br /> === Misc modules ===<br /> <br /> * petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor<br /> <br /> == System components ==<br /> <br /> [[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]<br /> <br /> Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.<br /> Here is described a default AmigaOS installation.<br /> <br /> * C<br /> This directory contains AmigaDOS '''C'''ommands<br /> * Classes<br /> contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...<br /> * Devs<br /> contains definition for '''Dev'''ices<br /> * Emulation<br /> contains files used for the 68k emulation (though E-UAE)<br /> * Fonts<br /> contains various systems fonts<br /> * Internet<br /> contains a dialer to connect to Internet<br /> * Kickstart<br /> contains the kickstart modules<br /> * L<br /> contains hand'''l'''ers and filesystems<br /> * Libs<br /> contains dynamic '''Libr'''airies of functions<br /> * Locale<br /> contains all files used to localise the system (catalogs, keymaps...)<br /> * MUI<br /> contains the needed files for programs that use the MUI third party graphic interface<br /> * Prefs<br /> contains the preference programs used to customise AmigaOS<br /> * S<br /> contains the '''S'''cripts<br /> * SObjs<br /> contains .so shared object library files<br /> * Storage<br /> contains other optional files<br /> * System<br /> contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools<br /> * [[UserDoc:Utilities|Utilities]]<br /> contains several programs you can use to achieve some tasks on AmigaOS<br /> <br /> = Motorola 680x0 Emulators =<br /> <br /> For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.<br /> <br /> In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be &quot;switched off&quot;.<br /> <br /> Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. &quot;Native&quot; PowerPC programs were rare, and every time a PowerPC program called the system, a so called &quot;context switch&quot; occurred between the 680x0 and PowerPC code, often causing a large performance penalty.<br /> <br /> The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor. <br /> <br /> == Two 680x0 Emulators ==<br /> <br /> In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low &quot;reaction time&quot;, and is ideal for time critical parts, such as interrupts.<br /> <br /> The other is Petunia, the &quot;JIT emulator&quot;. A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.<br /> <br /> Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, &quot;on the fly&quot;.<br /> <br /> This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.<br /> <br /> == Features ==<br /> <br /> Emulated opcodes:<br /> * all user and supervisor level opcodes of the Motorola 68040<br /> * all FPU opcodes of the Motorola 68881/68882 <br /> <br /> AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.<br /> <br /> At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.<br /> <br /> == Removing the JIT Emulator ==<br /> <br /> Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.<br /> <br /> If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.<br /> <br /> Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the &quot;Sys:Kickstart/Kicklayout&quot; file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like &quot;DefaultJIT&quot;, or &quot;DefaultNoJIT&quot;.<br /> <br /> == Configuring the Emulators ==<br /> <br /> Petunia cooperates with a so called &quot;black list&quot;. By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.<br /> <br /> If an executable needs to be added to the list, then it can be done by extending the file &quot;DEVS:applications.dos&quot; with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.<br /> <br /> Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.<br /> <br /> Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.<br /> <br /> For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list. <br /> <br /> = AmigaOS boot procedure =<br /> <br /> Basically a computer with AmigaOS does the following when the power button is pushed:<br /> <br /> * [[File:Uboot.jpg|200px]]<br /> the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.<br /> * depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.<br /> * [[File:SLB.png|200px]]<br /> the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.<br /> The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.<br /> * [[File:Kmods loading.png|200px]]<br /> the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module<br /> * '''Loader''' executes the kickstart modules (Exec, devices, libraries...)<br /> * AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor<br /> * the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume<br /> * the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.<br /> * the Workbench is started<br /> <br /> At this point the user can use his/her computer.<br /> <br /> = How to make a Bootable USB Memory Stick for AmigaOS 4.1 =<br /> <br /> By Julian Margetson (&quot;Spectre660&quot;)<br /> <br /> Prerequisites:<br /> * USB memory stick of 2 GB or less in size.<br /> * It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.<br /> * Plug the USB memory stick into a USB port on your machine.<br /> * Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.<br /> <br /> Procedure:<br /> # You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.<br /> # Make certain that you have selected usbdisk.device and not any other device.<br /> # Click on &quot;Start&quot;<br /> # You will see the usb mass storage unit connected in a list.<br /> # Make sure that the Unit type displayed for the USB memory stick is &quot;Removable hard disk&quot;<br /> # Select that Unit by clicking on it.<br /> # The first thing that you need to do is to install the RDB onto the USB Memory Stick.<br /> # Click on the &quot;Install&quot; button.<br /> # A window Labeled &quot;RDB/disk geometry editing&quot; comes up.<br /> ## Towards the bottom of the window is the &quot;AmigaOne boot code (SLB)&quot; section.<br /> ## Select the &quot;Install&quot; button .<br /> ## A file requester &quot;Select AmigaOne Boot Code&quot; now comes up with the Drawer choice defaulting to &quot;l:&quot;<br /> ## Select file &quot;slb_v2&quot;. <br /> ## Select Ok.<br /> ## You are now returned to the &quot;RDB/disk geometry editing window&quot;.<br /> ## Select &quot;Ok-accept changes&quot;.<br /> # You are now returned to the display showing the attached USB unit.<br /> # Select &quot;Edit partitions and Filesystems&quot;. You will now see the Window 'Editing partitions for disk&quot;<br /> # Select &quot;Add partition&quot;<br /> # This defaults to using the whole device as a single partition.<br /> # It is possible to use create more partitions but for this tutorial we will only use one.<br /> # You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the &quot;Name&quot; box.<br /> # Now make sure that the Boxes &quot;Automount&quot; and &quot;Bootable&quot; are selected and show the &quot;Tick mark&quot;.<br /> # You need to set &quot;Boot priority&quot; to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the &quot;+&quot; to the right of the &quot;boot priority&quot; box. Normally you can set the boot priority to 2 .<br /> # Next it is time to select the file system to use.<br /> # Select &quot;Select filesystem/edit details&quot;.<br /> # The Window &quot;Editing details for partition 'USB0'&quot; ,or whatever partition name you used, comes up.<br /> ## Select the file system that you are going to use by selecting the pull down menu under &quot;Filesystem chooser&quot;.<br /> ## Only filesystems SFS/00 or SFS/02 will work for a bootable device.<br /> ## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.<br /> ## Next select Blocksize from the &quot;Blocksize&quot; pull down menu. 512 is the correct size to use.<br /> ## Now Select &quot;Ok-accept changes&quot;.<br /> ## Your are now returned to the &quot;Edit partitions for disk&quot; window.<br /> ## Again select &quot;Ok-accept changes&quot;<br /> # You are now returned to the window showing the USB mass storage unit list.<br /> # Select &quot;Save to disk&quot;<br /> # A requester pops up with the options &quot;Yes, Save.&quot; or &quot;No!&quot;<br /> # Select the &quot;Yes, save.&quot; option.<br /> # You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.<br /> # This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.<br /> # Select &quot;Yes, reboot NOW!&quot;.<br /> # Once you have rebooted connect your USB Memory Stick to a USB port.<br /> # A disk icon &quot;USB0:Uninitialized&quot; (or whatever partition name you used) appears on Workbench.<br /> # You now need to format the device.<br /> # To format Select this Icon and go to the Workbench &quot;Icons&quot; menu .<br /> # Select &quot;Format Disk&quot;<br /> # You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.<br /> # You can use either a full Format or a Quick Format. Full Format may take a few minutes.<br /> # Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=UserDoc:How_AmigaOS_Works&diff=7653 UserDoc:How AmigaOS Works 2014-05-04T14:33:28Z <p>Philippe Ferrucci: /* All AmigaOS components */</p> <hr /> <div>As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.<br /> <br /> In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.<br /> <br /> = Introduction =<br /> <br /> AmigaOS is made of different components which are either mandatory i.e. AmigaOS will not work without them or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.<br /> <br /> = The most important components =<br /> <br /> == Exec, the AmigaOS kernel ==<br /> <br /> Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible of running programs, dealing with computer memory, managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.<br /> <br /> It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.<br /> <br /> == AmigaDOS: the underlying system ==<br /> <br /> The word &quot;DOS&quot; was originally an acronym for &quot;Disk Operating System&quot;. Some say it should be &quot;Disk Based Operating System&quot; as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be &quot;Device Operating System&quot;.<br /> <br /> The whole AmigaDOS system includes things such as:<br /> <br /> * A set of commands that can be used in the Shell window and elsewhere.<br /> * A system for saving data to disk and retrieving it from disk.<br /> * A system for filing data on disks.<br /> * An interface for peripherals such as keyboards, monitors, printers, etc.<br /> * A method of running programs<br /> * A multitasking system for running more than one program at a time.<br /> * etc. etc. etc.<br /> <br /> Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.<br /> <br /> == The Graphics library ==<br /> <br /> The Graphics library handles every low level graphic operations like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.<br /> <br /> == Intuition ==<br /> <br /> The Intuition library is responsible for every graphical objects: windows, screens, gadgets, mouse pointers... It lays between any graphic program and the graphics library.<br /> <br /> == The Workbench ==<br /> <br /> The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.<br /> [[File:Wb.png|320px]]<br /> <br /> == The Shell ==<br /> <br /> While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.<br /> <br /> == ARexx - inter-program communication by scripting ==<br /> <br /> The ARexx scripting language can be used to operate the Workbench and the most important Amiga applications from a script containing ARexx commands. This is extremely useful to perform repetitive tasks or to do what the controlled application was not even design to do.<br /> After a learning curve, everybody can use ARexx as it is built in the system and the scripts can be executed immediately like any other tool.<br /> <br /> = How is my data stored? =<br /> == Files ==<br /> === Executable files ===<br /> Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.<br /> An example is a music player. When you start this executable, the player opens and you can start playing music files.<br /> <br /> AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The laters are executed inside an emulation that transcripts them into PowerPC code.<br /> <br /> ==== Scripts ====<br /> <br /> Scripts are text files containing a list of commands. So they are not strictly executables like ''binary code'' files but they can be executed by AmigaOS like if they were.<br /> This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.<br /> <br /> === Data files ===<br /> Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.<br /> <br /> == Directories/Drawers ==<br /> In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.<br /> Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.<br /> <br /> Note: directories are often called ''folders'' on other systems.<br /> <br /> == Disks, partitions and volumes ==<br /> === Disks ===<br /> Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.<br /> <br /> === Partitions ===<br /> A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.<br /> <br /> [[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]<br /> <br /> On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.<br /> <br /> === Volumes ===<br /> A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.<br /> <br /> = How to identify files/directories =<br /> <br /> == On the Workbench ==<br /> <br /> The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...<br /> <br /> In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.<br /> <br /> == In a shell ==<br /> <br /> In a shell you need to issue the command '''list''' to see if an object is a file or a directory.<br /> <br /> [[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]<br /> <br /> A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.<br /> <br /> Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.<br /> <br /> = All AmigaOS components =<br /> <br /> AmigaOS is made of components that are needed as soon as the system starts or later when the user or the system needs them.<br /> <br /> == Kickstart modules ==<br /> <br /> These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is some kind of director handling the work of all other components.<br /> These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:<br /> <br /> === Mandatory modules ===<br /> <br /> The following modules are required in any AmigaOS system. Without one of these, the system will not start.<br /> <br /> * kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.<br /> * loader - this component handles the loading of all other kickstart modules<br /> * battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time<br /> * bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS<br /> * bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS<br /> * con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface<br /> * console.device.kmod - it opens a window and reads/writes text to and from that window<br /> * diskboot.kmod - handles the booting of AmigaOS from a supported disk<br /> * diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS<br /> * dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories<br /> * elf.library.kmod - handles the loading of executable programs<br /> * env-handler.kmod - handles the read/writes of environment variables<br /> * FileSystem.resource.kmod - handles the use of the different filesystems<br /> * gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...<br /> * gameport.device.kmod - handles the read/writes of game pads and joysticks<br /> * graphics.library.kmod - collection of functions used to draw graphic elements on the monitor<br /> * hunk.library.kmod - set of functions to read a data stream into memory<br /> * input.device.kmod - handles of input events like keyboard events or mouse clicks<br /> * intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)<br /> * layers.library.kmod - set of functions to be used to handle different layers in graphic operations<br /> * keyboard.device.kmod - driver for the keyboard<br /> * keymap.library.kmod - functions to handle different keymaps<br /> * newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )<br /> * nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage<br /> * nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers<br /> * PCIGraphics.card - driver that supports the use of different graphic cards<br /> * ram-handler.kmod - functions that handles the '''Ram disk:''' special disk<br /> * ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk<br /> * ramlib.kmod - loads disk based libraries and devices for exec.library<br /> * rtg.library - library of functions perform lowlevel graphic operations on graphic cards<br /> * shell.kmod - the AmigaOS command line interface<br /> * strap.kmod - module that handles booting on different disk devices<br /> * timer.device.kmod - driver to give access to timing functions<br /> <br /> === Filesystem support ===<br /> <br /> These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.<br /> <br /> * CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...<br /> * SmartFilesystem - allows to store data on partitions in SFS0 and SFS2<br /> * JXFileSystem - allows to create partitions in JXFS<br /> * FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts<br /> * diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules<br /> <br /> === Hardware drivers ===<br /> <br /> ==== Graphic cards drivers ====<br /> <br /> * 3dfxVoodoo.chip<br /> * 3DLabsPermedia2.chip<br /> * ATIRadeon.chip<br /> * RadeonHD.chip<br /> * siliconmotion502.chip<br /> <br /> ==== Disk drivers ====<br /> <br /> Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.<br /> <br /> * it8212ide.device.kmod<br /> * lsi53c8xx.device.kmod<br /> * sam460sata.device.kmod<br /> * sii3112ide.device.kmod<br /> * sii3512ide.device.kmod<br /> * sii3114ide.device.kmod<br /> * sii0680ide.device.kmod<br /> * sii3132ide.device.kmod<br /> <br /> ==== USB drivers ====<br /> <br /> * hub.usbfd<br /> * usbsys.device<br /> * usbresource.library<br /> * ehci.usbhcd<br /> * ohci.usbhcd<br /> * uhci.usbhcd<br /> * massstorage.usbfd<br /> <br /> ==== Other drivers ====<br /> <br /> * bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded<br /> * bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded<br /> * fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers<br /> * i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers<br /> * xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000<br /> <br /> === Misc modules ===<br /> <br /> * petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor<br /> <br /> == System components ==<br /> <br /> [[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]<br /> <br /> Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.<br /> Here is described a default AmigaOS installation.<br /> <br /> * C<br /> This directory contains AmigaDOS '''C'''ommands<br /> * Classes<br /> contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...<br /> * Devs<br /> contains definition for '''Dev'''ices<br /> * Emulation<br /> contains files used for the 68k emulation (though E-UAE)<br /> * Fonts<br /> contains various systems fonts<br /> * Internet<br /> contains a dialer to connect to Internet<br /> * Kickstart<br /> contains the kickstart modules<br /> * L<br /> contains hand'''l'''ers and filesystems<br /> * Libs<br /> contains dynamic '''Libr'''airies of functions<br /> * Locale<br /> contains all files used to localise the system (catalogs, keymaps...)<br /> * MUI<br /> contains the needed files for programs that use the MUI third party graphic interface<br /> * Prefs<br /> contains the preference programs used to customise AmigaOS<br /> * S<br /> contains the '''S'''cripts<br /> * SObjs<br /> contains .so shared object library files<br /> * Storage<br /> contains other optional files<br /> * System<br /> contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools<br /> * Utilities<br /> contains several utilities<br /> <br /> = Motorola 680x0 Emulators =<br /> <br /> For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.<br /> <br /> In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be &quot;switched off&quot;.<br /> <br /> Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. &quot;Native&quot; PowerPC programs were rare, and every time a PowerPC program called the system, a so called &quot;context switch&quot; occurred between the 680x0 and PowerPC code, often causing a large performance penalty.<br /> <br /> The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor. <br /> <br /> == Two 680x0 Emulators ==<br /> <br /> In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low &quot;reaction time&quot;, and is ideal for time critical parts, such as interrupts.<br /> <br /> The other is Petunia, the &quot;JIT emulator&quot;. A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.<br /> <br /> Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, &quot;on the fly&quot;.<br /> <br /> This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.<br /> <br /> == Features ==<br /> <br /> Emulated opcodes:<br /> * all user and supervisor level opcodes of the Motorola 68040<br /> * all FPU opcodes of the Motorola 68881/68882 <br /> <br /> AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.<br /> <br /> At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.<br /> <br /> == Removing the JIT Emulator ==<br /> <br /> Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.<br /> <br /> If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.<br /> <br /> Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the &quot;Sys:Kickstart/Kicklayout&quot; file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like &quot;DefaultJIT&quot;, or &quot;DefaultNoJIT&quot;.<br /> <br /> == Configuring the Emulators ==<br /> <br /> Petunia cooperates with a so called &quot;black list&quot;. By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.<br /> <br /> If an executable needs to be added to the list, then it can be done by extending the file &quot;DEVS:applications.dos&quot; with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.<br /> <br /> Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.<br /> <br /> Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.<br /> <br /> For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list. <br /> <br /> = AmigaOS boot procedure =<br /> <br /> Basically a computer with AmigaOS does the following when the power button is pushed:<br /> <br /> * [[File:Uboot.jpg|200px]]<br /> the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.<br /> * depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.<br /> * [[File:SLB.png|200px]]<br /> the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.<br /> The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.<br /> * [[File:Kmods loading.png|200px]]<br /> the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module<br /> * '''Loader''' executes the kickstart modules (Exec, devices, libraries...)<br /> * AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor<br /> * the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume<br /> * the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.<br /> * the Workbench is started<br /> <br /> At this point the user can use his/her computer.<br /> <br /> = How to make a Bootable USB Memory Stick for AmigaOS 4.1 =<br /> <br /> By Julian Margetson (&quot;Spectre660&quot;)<br /> <br /> Prerequisites:<br /> * USB memory stick of 2 GB or less in size.<br /> * It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.<br /> * Plug the USB memory stick into a USB port on your machine.<br /> * Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.<br /> <br /> Procedure:<br /> # You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.<br /> # Make certain that you have selected usbdisk.device and not any other device.<br /> # Click on &quot;Start&quot;<br /> # You will see the usb mass storage unit connected in a list.<br /> # Make sure that the Unit type displayed for the USB memory stick is &quot;Removable hard disk&quot;<br /> # Select that Unit by clicking on it.<br /> # The first thing that you need to do is to install the RDB onto the USB Memory Stick.<br /> # Click on the &quot;Install&quot; button.<br /> # A window Labeled &quot;RDB/disk geometry editing&quot; comes up.<br /> ## Towards the bottom of the window is the &quot;AmigaOne boot code (SLB)&quot; section.<br /> ## Select the &quot;Install&quot; button .<br /> ## A file requester &quot;Select AmigaOne Boot Code&quot; now comes up with the Drawer choice defaulting to &quot;l:&quot;<br /> ## Select file &quot;slb_v2&quot;. <br /> ## Select Ok.<br /> ## You are now returned to the &quot;RDB/disk geometry editing window&quot;.<br /> ## Select &quot;Ok-accept changes&quot;.<br /> # You are now returned to the display showing the attached USB unit.<br /> # Select &quot;Edit partitions and Filesystems&quot;. You will now see the Window 'Editing partitions for disk&quot;<br /> # Select &quot;Add partition&quot;<br /> # This defaults to using the whole device as a single partition.<br /> # It is possible to use create more partitions but for this tutorial we will only use one.<br /> # You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the &quot;Name&quot; box.<br /> # Now make sure that the Boxes &quot;Automount&quot; and &quot;Bootable&quot; are selected and show the &quot;Tick mark&quot;.<br /> # You need to set &quot;Boot priority&quot; to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the &quot;+&quot; to the right of the &quot;boot priority&quot; box. Normally you can set the boot priority to 2 .<br /> # Next it is time to select the file system to use.<br /> # Select &quot;Select filesystem/edit details&quot;.<br /> # The Window &quot;Editing details for partition 'USB0'&quot; ,or whatever partition name you used, comes up.<br /> ## Select the file system that you are going to use by selecting the pull down menu under &quot;Filesystem chooser&quot;.<br /> ## Only filesystems SFS/00 or SFS/02 will work for a bootable device.<br /> ## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.<br /> ## Next select Blocksize from the &quot;Blocksize&quot; pull down menu. 512 is the correct size to use.<br /> ## Now Select &quot;Ok-accept changes&quot;.<br /> ## Your are now returned to the &quot;Edit partitions for disk&quot; window.<br /> ## Again select &quot;Ok-accept changes&quot;<br /> # You are now returned to the window showing the USB mass storage unit list.<br /> # Select &quot;Save to disk&quot;<br /> # A requester pops up with the options &quot;Yes, Save.&quot; or &quot;No!&quot;<br /> # Select the &quot;Yes, save.&quot; option.<br /> # You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.<br /> # This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.<br /> # Select &quot;Yes, reboot NOW!&quot;.<br /> # Once you have rebooted connect your USB Memory Stick to a USB port.<br /> # A disk icon &quot;USB0:Uninitialized&quot; (or whatever partition name you used) appears on Workbench.<br /> # You now need to format the device.<br /> # To format Select this Icon and go to the Workbench &quot;Icons&quot; menu .<br /> # Select &quot;Format Disk&quot;<br /> # You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.<br /> # You can use either a full Format or a Quick Format. Full Format may take a few minutes.<br /> # Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=UserDoc:How_AmigaOS_Works&diff=7652 UserDoc:How AmigaOS Works 2014-05-04T14:28:45Z <p>Philippe Ferrucci: /* Introduction */</p> <hr /> <div>As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.<br /> <br /> In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.<br /> <br /> = Introduction =<br /> <br /> AmigaOS is made of different components which are either mandatory i.e. AmigaOS will not work without them or components the user can choose to use or not. All these components can have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.<br /> <br /> = The most important components =<br /> <br /> == Exec, the AmigaOS kernel ==<br /> <br /> Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible of running programs, dealing with computer memory, managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.<br /> <br /> It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.<br /> <br /> == AmigaDOS: the underlying system ==<br /> <br /> The word &quot;DOS&quot; was originally an acronym for &quot;Disk Operating System&quot;. Some say it should be &quot;Disk Based Operating System&quot; as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be &quot;Device Operating System&quot;.<br /> <br /> The whole AmigaDOS system includes things such as:<br /> <br /> * A set of commands that can be used in the Shell window and elsewhere.<br /> * A system for saving data to disk and retrieving it from disk.<br /> * A system for filing data on disks.<br /> * An interface for peripherals such as keyboards, monitors, printers, etc.<br /> * A method of running programs<br /> * A multitasking system for running more than one program at a time.<br /> * etc. etc. etc.<br /> <br /> Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.<br /> <br /> == The Graphics library ==<br /> <br /> The Graphics library handles every low level graphic operations like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.<br /> <br /> == Intuition ==<br /> <br /> The Intuition library is responsible for every graphical objects: windows, screens, gadgets, mouse pointers... It lays between any graphic program and the graphics library.<br /> <br /> == The Workbench ==<br /> <br /> The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.<br /> [[File:Wb.png|320px]]<br /> <br /> == The Shell ==<br /> <br /> While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.<br /> <br /> == ARexx - inter-program communication by scripting ==<br /> <br /> The ARexx scripting language can be used to operate the Workbench and the most important Amiga applications from a script containing ARexx commands. This is extremely useful to perform repetitive tasks or to do what the controlled application was not even design to do.<br /> After a learning curve, everybody can use ARexx as it is built in the system and the scripts can be executed immediately like any other tool.<br /> <br /> = How is my data stored? =<br /> == Files ==<br /> === Executable files ===<br /> Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.<br /> An example is a music player. When you start this executable, the player opens and you can start playing music files.<br /> <br /> AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The laters are executed inside an emulation that transcripts them into PowerPC code.<br /> <br /> ==== Scripts ====<br /> <br /> Scripts are text files containing a list of commands. So they are not strictly executables like ''binary code'' files but they can be executed by AmigaOS like if they were.<br /> This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.<br /> <br /> === Data files ===<br /> Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.<br /> <br /> == Directories/Drawers ==<br /> In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.<br /> Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.<br /> <br /> Note: directories are often called ''folders'' on other systems.<br /> <br /> == Disks, partitions and volumes ==<br /> === Disks ===<br /> Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.<br /> <br /> === Partitions ===<br /> A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.<br /> <br /> [[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]<br /> <br /> On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.<br /> <br /> === Volumes ===<br /> A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.<br /> <br /> = How to identify files/directories =<br /> <br /> == On the Workbench ==<br /> <br /> The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...<br /> <br /> In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.<br /> <br /> == In a shell ==<br /> <br /> In a shell you need to issue the command '''list''' to see if an object is a file or a directory.<br /> <br /> [[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]<br /> <br /> A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.<br /> <br /> Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.<br /> <br /> = All AmigaOS components =<br /> <br /> AmigaOS allows the user to choosemade of different components which have their own job in the system. The most important ones are mandatory. Without them the system does not even start. Other components are less important and the user can choose to use them or not. This is the case of drivers. For instance, a device driver may be omitted. If so, the corresponding device will just not work as AmigaOS will have no driver that allows it to know what to do with this device.<br /> <br /> == Kickstart modules ==<br /> <br /> These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is some kind of director handling the work of all other components.<br /> These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:<br /> <br /> === Mandatory modules ===<br /> <br /> The following modules are required in any AmigaOS system. Without one of these, the system will not start.<br /> <br /> * kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.<br /> * loader - this component handles the loading of all other kickstart modules<br /> * battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time<br /> * bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS<br /> * bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS<br /> * con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface<br /> * console.device.kmod - it opens a window and reads/writes text to and from that window<br /> * diskboot.kmod - handles the booting of AmigaOS from a supported disk<br /> * diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS<br /> * dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories<br /> * elf.library.kmod - handles the loading of executable programs<br /> * env-handler.kmod - handles the read/writes of environment variables<br /> * FileSystem.resource.kmod - handles the use of the different filesystems<br /> * gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...<br /> * gameport.device.kmod - handles the read/writes of game pads and joysticks<br /> * graphics.library.kmod - collection of functions used to draw graphic elements on the monitor<br /> * hunk.library.kmod - set of functions to read a data stream into memory<br /> * input.device.kmod - handles of input events like keyboard events or mouse clicks<br /> * intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)<br /> * layers.library.kmod - set of functions to be used to handle different layers in graphic operations<br /> * keyboard.device.kmod - driver for the keyboard<br /> * keymap.library.kmod - functions to handle different keymaps<br /> * newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )<br /> * nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage<br /> * nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers<br /> * PCIGraphics.card - driver that supports the use of different graphic cards<br /> * ram-handler.kmod - functions that handles the '''Ram disk:''' special disk<br /> * ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk<br /> * ramlib.kmod - loads disk based libraries and devices for exec.library<br /> * rtg.library - library of functions perform lowlevel graphic operations on graphic cards<br /> * shell.kmod - the AmigaOS command line interface<br /> * strap.kmod - module that handles booting on different disk devices<br /> * timer.device.kmod - driver to give access to timing functions<br /> <br /> === Filesystem support ===<br /> <br /> These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.<br /> <br /> * CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...<br /> * SmartFilesystem - allows to store data on partitions in SFS0 and SFS2<br /> * JXFileSystem - allows to create partitions in JXFS<br /> * FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts<br /> * diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules<br /> <br /> === Hardware drivers ===<br /> <br /> ==== Graphic cards drivers ====<br /> <br /> * 3dfxVoodoo.chip<br /> * 3DLabsPermedia2.chip<br /> * ATIRadeon.chip<br /> * RadeonHD.chip<br /> * siliconmotion502.chip<br /> <br /> ==== Disk drivers ====<br /> <br /> Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.<br /> <br /> * it8212ide.device.kmod<br /> * lsi53c8xx.device.kmod<br /> * sam460sata.device.kmod<br /> * sii3112ide.device.kmod<br /> * sii3512ide.device.kmod<br /> * sii3114ide.device.kmod<br /> * sii0680ide.device.kmod<br /> * sii3132ide.device.kmod<br /> <br /> ==== USB drivers ====<br /> <br /> * hub.usbfd<br /> * usbsys.device<br /> * usbresource.library<br /> * ehci.usbhcd<br /> * ohci.usbhcd<br /> * uhci.usbhcd<br /> * massstorage.usbfd<br /> <br /> ==== Other drivers ====<br /> <br /> * bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded<br /> * bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded<br /> * fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers<br /> * i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers<br /> * xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000<br /> <br /> === Misc modules ===<br /> <br /> * petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor<br /> <br /> == System components ==<br /> <br /> [[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]<br /> <br /> Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.<br /> Here is described a default AmigaOS installation.<br /> <br /> * C<br /> This directory contains AmigaDOS '''C'''ommands<br /> * Classes<br /> contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...<br /> * Devs<br /> contains definition for '''Dev'''ices<br /> * Emulation<br /> contains files used for the 68k emulation (though E-UAE)<br /> * Fonts<br /> contains various systems fonts<br /> * Internet<br /> contains a dialer to connect to Internet<br /> * Kickstart<br /> contains the kickstart modules<br /> * L<br /> contains hand'''l'''ers and filesystems<br /> * Libs<br /> contains dynamic '''Libr'''airies of functions<br /> * Locale<br /> contains all files used to localise the system (catalogs, keymaps...)<br /> * MUI<br /> contains the needed files for programs that use the MUI third party graphic interface<br /> * Prefs<br /> contains the preference programs used to customise AmigaOS<br /> * S<br /> contains the '''S'''cripts<br /> * SObjs<br /> contains .so shared object library files<br /> * Storage<br /> contains other optional files<br /> * System<br /> contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools<br /> * Utilities<br /> contains several utilities<br /> <br /> = Motorola 680x0 Emulators =<br /> <br /> For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.<br /> <br /> In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be &quot;switched off&quot;.<br /> <br /> Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. &quot;Native&quot; PowerPC programs were rare, and every time a PowerPC program called the system, a so called &quot;context switch&quot; occurred between the 680x0 and PowerPC code, often causing a large performance penalty.<br /> <br /> The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor. <br /> <br /> == Two 680x0 Emulators ==<br /> <br /> In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low &quot;reaction time&quot;, and is ideal for time critical parts, such as interrupts.<br /> <br /> The other is Petunia, the &quot;JIT emulator&quot;. A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.<br /> <br /> Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, &quot;on the fly&quot;.<br /> <br /> This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.<br /> <br /> == Features ==<br /> <br /> Emulated opcodes:<br /> * all user and supervisor level opcodes of the Motorola 68040<br /> * all FPU opcodes of the Motorola 68881/68882 <br /> <br /> AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.<br /> <br /> At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.<br /> <br /> == Removing the JIT Emulator ==<br /> <br /> Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.<br /> <br /> If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.<br /> <br /> Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the &quot;Sys:Kickstart/Kicklayout&quot; file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like &quot;DefaultJIT&quot;, or &quot;DefaultNoJIT&quot;.<br /> <br /> == Configuring the Emulators ==<br /> <br /> Petunia cooperates with a so called &quot;black list&quot;. By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.<br /> <br /> If an executable needs to be added to the list, then it can be done by extending the file &quot;DEVS:applications.dos&quot; with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.<br /> <br /> Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.<br /> <br /> Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.<br /> <br /> For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list. <br /> <br /> = AmigaOS boot procedure =<br /> <br /> Basically a computer with AmigaOS does the following when the power button is pushed:<br /> <br /> * [[File:Uboot.jpg|200px]]<br /> the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.<br /> * depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.<br /> * [[File:SLB.png|200px]]<br /> the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.<br /> The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.<br /> * [[File:Kmods loading.png|200px]]<br /> the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module<br /> * '''Loader''' executes the kickstart modules (Exec, devices, libraries...)<br /> * AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor<br /> * the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume<br /> * the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.<br /> * the Workbench is started<br /> <br /> At this point the user can use his/her computer.<br /> <br /> = How to make a Bootable USB Memory Stick for AmigaOS 4.1 =<br /> <br /> By Julian Margetson (&quot;Spectre660&quot;)<br /> <br /> Prerequisites:<br /> * USB memory stick of 2 GB or less in size.<br /> * It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.<br /> * Plug the USB memory stick into a USB port on your machine.<br /> * Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.<br /> <br /> Procedure:<br /> # You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.<br /> # Make certain that you have selected usbdisk.device and not any other device.<br /> # Click on &quot;Start&quot;<br /> # You will see the usb mass storage unit connected in a list.<br /> # Make sure that the Unit type displayed for the USB memory stick is &quot;Removable hard disk&quot;<br /> # Select that Unit by clicking on it.<br /> # The first thing that you need to do is to install the RDB onto the USB Memory Stick.<br /> # Click on the &quot;Install&quot; button.<br /> # A window Labeled &quot;RDB/disk geometry editing&quot; comes up.<br /> ## Towards the bottom of the window is the &quot;AmigaOne boot code (SLB)&quot; section.<br /> ## Select the &quot;Install&quot; button .<br /> ## A file requester &quot;Select AmigaOne Boot Code&quot; now comes up with the Drawer choice defaulting to &quot;l:&quot;<br /> ## Select file &quot;slb_v2&quot;. <br /> ## Select Ok.<br /> ## You are now returned to the &quot;RDB/disk geometry editing window&quot;.<br /> ## Select &quot;Ok-accept changes&quot;.<br /> # You are now returned to the display showing the attached USB unit.<br /> # Select &quot;Edit partitions and Filesystems&quot;. You will now see the Window 'Editing partitions for disk&quot;<br /> # Select &quot;Add partition&quot;<br /> # This defaults to using the whole device as a single partition.<br /> # It is possible to use create more partitions but for this tutorial we will only use one.<br /> # You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the &quot;Name&quot; box.<br /> # Now make sure that the Boxes &quot;Automount&quot; and &quot;Bootable&quot; are selected and show the &quot;Tick mark&quot;.<br /> # You need to set &quot;Boot priority&quot; to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the &quot;+&quot; to the right of the &quot;boot priority&quot; box. Normally you can set the boot priority to 2 .<br /> # Next it is time to select the file system to use.<br /> # Select &quot;Select filesystem/edit details&quot;.<br /> # The Window &quot;Editing details for partition 'USB0'&quot; ,or whatever partition name you used, comes up.<br /> ## Select the file system that you are going to use by selecting the pull down menu under &quot;Filesystem chooser&quot;.<br /> ## Only filesystems SFS/00 or SFS/02 will work for a bootable device.<br /> ## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.<br /> ## Next select Blocksize from the &quot;Blocksize&quot; pull down menu. 512 is the correct size to use.<br /> ## Now Select &quot;Ok-accept changes&quot;.<br /> ## Your are now returned to the &quot;Edit partitions for disk&quot; window.<br /> ## Again select &quot;Ok-accept changes&quot;<br /> # You are now returned to the window showing the USB mass storage unit list.<br /> # Select &quot;Save to disk&quot;<br /> # A requester pops up with the options &quot;Yes, Save.&quot; or &quot;No!&quot;<br /> # Select the &quot;Yes, save.&quot; option.<br /> # You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.<br /> # This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.<br /> # Select &quot;Yes, reboot NOW!&quot;.<br /> # Once you have rebooted connect your USB Memory Stick to a USB port.<br /> # A disk icon &quot;USB0:Uninitialized&quot; (or whatever partition name you used) appears on Workbench.<br /> # You now need to format the device.<br /> # To format Select this Icon and go to the Workbench &quot;Icons&quot; menu .<br /> # Select &quot;Format Disk&quot;<br /> # You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.<br /> # You can use either a full Format or a Quick Format. Full Format may take a few minutes.<br /> # Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=UserDoc:How_AmigaOS_Works&diff=7651 UserDoc:How AmigaOS Works 2014-05-04T14:27:23Z <p>Philippe Ferrucci: /* All AmigaOS components */</p> <hr /> <div>As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.<br /> <br /> In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.<br /> <br /> = Introduction =<br /> <br /> AmigaOS is made of different components which are either mandatory i.e. AmigaOS will not work without them or components the user can choose to use or not. All these components can have have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.<br /> <br /> = The most important components =<br /> <br /> == Exec, the AmigaOS kernel ==<br /> <br /> Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible of running programs, dealing with computer memory, managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.<br /> <br /> It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.<br /> <br /> == AmigaDOS: the underlying system ==<br /> <br /> The word &quot;DOS&quot; was originally an acronym for &quot;Disk Operating System&quot;. Some say it should be &quot;Disk Based Operating System&quot; as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be &quot;Device Operating System&quot;.<br /> <br /> The whole AmigaDOS system includes things such as:<br /> <br /> * A set of commands that can be used in the Shell window and elsewhere.<br /> * A system for saving data to disk and retrieving it from disk.<br /> * A system for filing data on disks.<br /> * An interface for peripherals such as keyboards, monitors, printers, etc.<br /> * A method of running programs<br /> * A multitasking system for running more than one program at a time.<br /> * etc. etc. etc.<br /> <br /> Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.<br /> <br /> == The Graphics library ==<br /> <br /> The Graphics library handles every low level graphic operations like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.<br /> <br /> == Intuition ==<br /> <br /> The Intuition library is responsible for every graphical objects: windows, screens, gadgets, mouse pointers... It lays between any graphic program and the graphics library.<br /> <br /> == The Workbench ==<br /> <br /> The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.<br /> [[File:Wb.png|320px]]<br /> <br /> == The Shell ==<br /> <br /> While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.<br /> <br /> == ARexx - inter-program communication by scripting ==<br /> <br /> The ARexx scripting language can be used to operate the Workbench and the most important Amiga applications from a script containing ARexx commands. This is extremely useful to perform repetitive tasks or to do what the controlled application was not even design to do.<br /> After a learning curve, everybody can use ARexx as it is built in the system and the scripts can be executed immediately like any other tool.<br /> <br /> = How is my data stored? =<br /> == Files ==<br /> === Executable files ===<br /> Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.<br /> An example is a music player. When you start this executable, the player opens and you can start playing music files.<br /> <br /> AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The laters are executed inside an emulation that transcripts them into PowerPC code.<br /> <br /> ==== Scripts ====<br /> <br /> Scripts are text files containing a list of commands. So they are not strictly executables like ''binary code'' files but they can be executed by AmigaOS like if they were.<br /> This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.<br /> <br /> === Data files ===<br /> Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.<br /> <br /> == Directories/Drawers ==<br /> In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.<br /> Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.<br /> <br /> Note: directories are often called ''folders'' on other systems.<br /> <br /> == Disks, partitions and volumes ==<br /> === Disks ===<br /> Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.<br /> <br /> === Partitions ===<br /> A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.<br /> <br /> [[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]<br /> <br /> On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.<br /> <br /> === Volumes ===<br /> A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.<br /> <br /> = How to identify files/directories =<br /> <br /> == On the Workbench ==<br /> <br /> The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...<br /> <br /> In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.<br /> <br /> == In a shell ==<br /> <br /> In a shell you need to issue the command '''list''' to see if an object is a file or a directory.<br /> <br /> [[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]<br /> <br /> A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.<br /> <br /> Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.<br /> <br /> = All AmigaOS components =<br /> <br /> AmigaOS allows the user to choosemade of different components which have their own job in the system. The most important ones are mandatory. Without them the system does not even start. Other components are less important and the user can choose to use them or not. This is the case of drivers. For instance, a device driver may be omitted. If so, the corresponding device will just not work as AmigaOS will have no driver that allows it to know what to do with this device.<br /> <br /> == Kickstart modules ==<br /> <br /> These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is some kind of director handling the work of all other components.<br /> These Kickstart modules are loaded at the beginning of the operating system boot process (read [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|here]]). You can find all them in the '''Kickstart''' directory in the system volume. Here is a list:<br /> <br /> === Mandatory modules ===<br /> <br /> The following modules are required in any AmigaOS system. Without one of these, the system will not start.<br /> <br /> * kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.<br /> * loader - this component handles the loading of all other kickstart modules<br /> * battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time<br /> * bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS<br /> * bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS<br /> * con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface<br /> * console.device.kmod - it opens a window and reads/writes text to and from that window<br /> * diskboot.kmod - handles the booting of AmigaOS from a supported disk<br /> * diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS<br /> * dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories<br /> * elf.library.kmod - handles the loading of executable programs<br /> * env-handler.kmod - handles the read/writes of environment variables<br /> * FileSystem.resource.kmod - handles the use of the different filesystems<br /> * gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...<br /> * gameport.device.kmod - handles the read/writes of game pads and joysticks<br /> * graphics.library.kmod - collection of functions used to draw graphic elements on the monitor<br /> * hunk.library.kmod - set of functions to read a data stream into memory<br /> * input.device.kmod - handles of input events like keyboard events or mouse clicks<br /> * intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)<br /> * layers.library.kmod - set of functions to be used to handle different layers in graphic operations<br /> * keyboard.device.kmod - driver for the keyboard<br /> * keymap.library.kmod - functions to handle different keymaps<br /> * newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )<br /> * nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage<br /> * nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers<br /> * PCIGraphics.card - driver that supports the use of different graphic cards<br /> * ram-handler.kmod - functions that handles the '''Ram disk:''' special disk<br /> * ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk<br /> * ramlib.kmod - loads disk based libraries and devices for exec.library<br /> * rtg.library - library of functions perform lowlevel graphic operations on graphic cards<br /> * shell.kmod - the AmigaOS command line interface<br /> * strap.kmod - module that handles booting on different disk devices<br /> * timer.device.kmod - driver to give access to timing functions<br /> <br /> === Filesystem support ===<br /> <br /> These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.<br /> <br /> * CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...<br /> * SmartFilesystem - allows to store data on partitions in SFS0 and SFS2<br /> * JXFileSystem - allows to create partitions in JXFS<br /> * FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts<br /> * diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules<br /> <br /> === Hardware drivers ===<br /> <br /> ==== Graphic cards drivers ====<br /> <br /> * 3dfxVoodoo.chip<br /> * 3DLabsPermedia2.chip<br /> * ATIRadeon.chip<br /> * RadeonHD.chip<br /> * siliconmotion502.chip<br /> <br /> ==== Disk drivers ====<br /> <br /> Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.<br /> <br /> * it8212ide.device.kmod<br /> * lsi53c8xx.device.kmod<br /> * sam460sata.device.kmod<br /> * sii3112ide.device.kmod<br /> * sii3512ide.device.kmod<br /> * sii3114ide.device.kmod<br /> * sii0680ide.device.kmod<br /> * sii3132ide.device.kmod<br /> <br /> ==== USB drivers ====<br /> <br /> * hub.usbfd<br /> * usbsys.device<br /> * usbresource.library<br /> * ehci.usbhcd<br /> * ohci.usbhcd<br /> * uhci.usbhcd<br /> * massstorage.usbfd<br /> <br /> ==== Other drivers ====<br /> <br /> * bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded<br /> * bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded<br /> * fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers<br /> * i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers<br /> * xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000<br /> <br /> === Misc modules ===<br /> <br /> * petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor<br /> <br /> == System components ==<br /> <br /> [[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]<br /> <br /> Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.<br /> Here is described a default AmigaOS installation.<br /> <br /> * C<br /> This directory contains AmigaDOS '''C'''ommands<br /> * Classes<br /> contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...<br /> * Devs<br /> contains definition for '''Dev'''ices<br /> * Emulation<br /> contains files used for the 68k emulation (though E-UAE)<br /> * Fonts<br /> contains various systems fonts<br /> * Internet<br /> contains a dialer to connect to Internet<br /> * Kickstart<br /> contains the kickstart modules<br /> * L<br /> contains hand'''l'''ers and filesystems<br /> * Libs<br /> contains dynamic '''Libr'''airies of functions<br /> * Locale<br /> contains all files used to localise the system (catalogs, keymaps...)<br /> * MUI<br /> contains the needed files for programs that use the MUI third party graphic interface<br /> * Prefs<br /> contains the preference programs used to customise AmigaOS<br /> * S<br /> contains the '''S'''cripts<br /> * SObjs<br /> contains .so shared object library files<br /> * Storage<br /> contains other optional files<br /> * System<br /> contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools<br /> * Utilities<br /> contains several utilities<br /> <br /> = Motorola 680x0 Emulators =<br /> <br /> For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.<br /> <br /> In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be &quot;switched off&quot;.<br /> <br /> Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. &quot;Native&quot; PowerPC programs were rare, and every time a PowerPC program called the system, a so called &quot;context switch&quot; occurred between the 680x0 and PowerPC code, often causing a large performance penalty.<br /> <br /> The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor. <br /> <br /> == Two 680x0 Emulators ==<br /> <br /> In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low &quot;reaction time&quot;, and is ideal for time critical parts, such as interrupts.<br /> <br /> The other is Petunia, the &quot;JIT emulator&quot;. A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.<br /> <br /> Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, &quot;on the fly&quot;.<br /> <br /> This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.<br /> <br /> == Features ==<br /> <br /> Emulated opcodes:<br /> * all user and supervisor level opcodes of the Motorola 68040<br /> * all FPU opcodes of the Motorola 68881/68882 <br /> <br /> AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.<br /> <br /> At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.<br /> <br /> == Removing the JIT Emulator ==<br /> <br /> Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.<br /> <br /> If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.<br /> <br /> Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the &quot;Sys:Kickstart/Kicklayout&quot; file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like &quot;DefaultJIT&quot;, or &quot;DefaultNoJIT&quot;.<br /> <br /> == Configuring the Emulators ==<br /> <br /> Petunia cooperates with a so called &quot;black list&quot;. By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.<br /> <br /> If an executable needs to be added to the list, then it can be done by extending the file &quot;DEVS:applications.dos&quot; with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.<br /> <br /> Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.<br /> <br /> Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.<br /> <br /> For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list. <br /> <br /> = AmigaOS boot procedure =<br /> <br /> Basically a computer with AmigaOS does the following when the power button is pushed:<br /> <br /> * [[File:Uboot.jpg|200px]]<br /> the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.<br /> * depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.<br /> * [[File:SLB.png|200px]]<br /> the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.<br /> The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.<br /> * [[File:Kmods loading.png|200px]]<br /> the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module<br /> * '''Loader''' executes the kickstart modules (Exec, devices, libraries...)<br /> * AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor<br /> * the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume<br /> * the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.<br /> * the Workbench is started<br /> <br /> At this point the user can use his/her computer.<br /> <br /> = How to make a Bootable USB Memory Stick for AmigaOS 4.1 =<br /> <br /> By Julian Margetson (&quot;Spectre660&quot;)<br /> <br /> Prerequisites:<br /> * USB memory stick of 2 GB or less in size.<br /> * It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.<br /> * Plug the USB memory stick into a USB port on your machine.<br /> * Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.<br /> <br /> Procedure:<br /> # You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.<br /> # Make certain that you have selected usbdisk.device and not any other device.<br /> # Click on &quot;Start&quot;<br /> # You will see the usb mass storage unit connected in a list.<br /> # Make sure that the Unit type displayed for the USB memory stick is &quot;Removable hard disk&quot;<br /> # Select that Unit by clicking on it.<br /> # The first thing that you need to do is to install the RDB onto the USB Memory Stick.<br /> # Click on the &quot;Install&quot; button.<br /> # A window Labeled &quot;RDB/disk geometry editing&quot; comes up.<br /> ## Towards the bottom of the window is the &quot;AmigaOne boot code (SLB)&quot; section.<br /> ## Select the &quot;Install&quot; button .<br /> ## A file requester &quot;Select AmigaOne Boot Code&quot; now comes up with the Drawer choice defaulting to &quot;l:&quot;<br /> ## Select file &quot;slb_v2&quot;. <br /> ## Select Ok.<br /> ## You are now returned to the &quot;RDB/disk geometry editing window&quot;.<br /> ## Select &quot;Ok-accept changes&quot;.<br /> # You are now returned to the display showing the attached USB unit.<br /> # Select &quot;Edit partitions and Filesystems&quot;. You will now see the Window 'Editing partitions for disk&quot;<br /> # Select &quot;Add partition&quot;<br /> # This defaults to using the whole device as a single partition.<br /> # It is possible to use create more partitions but for this tutorial we will only use one.<br /> # You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the &quot;Name&quot; box.<br /> # Now make sure that the Boxes &quot;Automount&quot; and &quot;Bootable&quot; are selected and show the &quot;Tick mark&quot;.<br /> # You need to set &quot;Boot priority&quot; to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the &quot;+&quot; to the right of the &quot;boot priority&quot; box. Normally you can set the boot priority to 2 .<br /> # Next it is time to select the file system to use.<br /> # Select &quot;Select filesystem/edit details&quot;.<br /> # The Window &quot;Editing details for partition 'USB0'&quot; ,or whatever partition name you used, comes up.<br /> ## Select the file system that you are going to use by selecting the pull down menu under &quot;Filesystem chooser&quot;.<br /> ## Only filesystems SFS/00 or SFS/02 will work for a bootable device.<br /> ## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.<br /> ## Next select Blocksize from the &quot;Blocksize&quot; pull down menu. 512 is the correct size to use.<br /> ## Now Select &quot;Ok-accept changes&quot;.<br /> ## Your are now returned to the &quot;Edit partitions for disk&quot; window.<br /> ## Again select &quot;Ok-accept changes&quot;<br /> # You are now returned to the window showing the USB mass storage unit list.<br /> # Select &quot;Save to disk&quot;<br /> # A requester pops up with the options &quot;Yes, Save.&quot; or &quot;No!&quot;<br /> # Select the &quot;Yes, save.&quot; option.<br /> # You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.<br /> # This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.<br /> # Select &quot;Yes, reboot NOW!&quot;.<br /> # Once you have rebooted connect your USB Memory Stick to a USB port.<br /> # A disk icon &quot;USB0:Uninitialized&quot; (or whatever partition name you used) appears on Workbench.<br /> # You now need to format the device.<br /> # To format Select this Icon and go to the Workbench &quot;Icons&quot; menu .<br /> # Select &quot;Format Disk&quot;<br /> # You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.<br /> # You can use either a full Format or a Quick Format. Full Format may take a few minutes.<br /> # Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=UserDoc:How_AmigaOS_Works&diff=7650 UserDoc:How AmigaOS Works 2014-05-04T14:15:38Z <p>Philippe Ferrucci: </p> <hr /> <div>As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.<br /> <br /> In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.<br /> <br /> = Introduction =<br /> <br /> AmigaOS is made of different components which are either mandatory i.e. AmigaOS will not work without them or components the user can choose to use or not. All these components can have have one or mutiple interfaces a user or a developer can use to operate with the components and through them to control the operating system.<br /> <br /> = The most important components =<br /> <br /> == Exec, the AmigaOS kernel ==<br /> <br /> Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible of running programs, dealing with computer memory, managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.<br /> <br /> It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.<br /> <br /> == AmigaDOS: the underlying system ==<br /> <br /> The word &quot;DOS&quot; was originally an acronym for &quot;Disk Operating System&quot;. Some say it should be &quot;Disk Based Operating System&quot; as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be &quot;Device Operating System&quot;.<br /> <br /> The whole AmigaDOS system includes things such as:<br /> <br /> * A set of commands that can be used in the Shell window and elsewhere.<br /> * A system for saving data to disk and retrieving it from disk.<br /> * A system for filing data on disks.<br /> * An interface for peripherals such as keyboards, monitors, printers, etc.<br /> * A method of running programs<br /> * A multitasking system for running more than one program at a time.<br /> * etc. etc. etc.<br /> <br /> Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.<br /> <br /> == The Graphics library ==<br /> <br /> The Graphics library handles every low level graphic operations like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.<br /> <br /> == Intuition ==<br /> <br /> The Intuition library is responsible for every graphical objects: windows, screens, gadgets, mouse pointers... It lays between any graphic program and the graphics library.<br /> <br /> == The Workbench ==<br /> <br /> The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.<br /> [[File:Wb.png|320px]]<br /> <br /> == The Shell ==<br /> <br /> While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.<br /> <br /> == ARexx - inter-program communication by scripting ==<br /> <br /> The ARexx scripting language can be used to operate the Workbench and the most important Amiga applications from a script containing ARexx commands. This is extremely useful to perform repetitive tasks or to do what the controlled application was not even design to do.<br /> After a learning curve, everybody can use ARexx as it is built in the system and the scripts can be executed immediately like any other tool.<br /> <br /> = How is my data stored? =<br /> == Files ==<br /> === Executable files ===<br /> Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.<br /> An example is a music player. When you start this executable, the player opens and you can start playing music files.<br /> <br /> AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The laters are executed inside an emulation that transcripts them into PowerPC code.<br /> <br /> ==== Scripts ====<br /> <br /> Scripts are text files containing a list of commands. So they are not strictly executables like ''binary code'' files but they can be executed by AmigaOS like if they were.<br /> This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.<br /> <br /> === Data files ===<br /> Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.<br /> <br /> == Directories/Drawers ==<br /> In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.<br /> Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.<br /> <br /> Note: directories are often called ''folders'' on other systems.<br /> <br /> == Disks, partitions and volumes ==<br /> === Disks ===<br /> Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.<br /> <br /> === Partitions ===<br /> A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.<br /> <br /> [[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]<br /> <br /> On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.<br /> <br /> === Volumes ===<br /> A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.<br /> <br /> = How to identify files/directories =<br /> <br /> == On the Workbench ==<br /> <br /> The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...<br /> <br /> In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.<br /> <br /> == In a shell ==<br /> <br /> In a shell you need to issue the command '''list''' to see if an object is a file or a directory.<br /> <br /> [[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]<br /> <br /> A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.<br /> <br /> Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.<br /> <br /> = All AmigaOS components =<br /> <br /> AmigaOS is made of different components which have their own job in the system. The most important ones are mandatory. Without them the system does not even start. Other components are less important and the user can choose to use them or not. This is the case of drivers. For instance, a device driver may be omitted. If so, the corresponding device will just not work as AmigaOS will have no driver that allows it to know what to do with this device.<br /> <br /> == Kickstart modules ==<br /> <br /> These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is some kind of director handling the work of all other components.<br /> You can find all these modules in the '''Kickstart''' directory in the system volume. Here is a list:<br /> <br /> === Mandatory modules ===<br /> <br /> The following modules are required in any AmigaOS system. Without one of these, the system will not start.<br /> <br /> * kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.<br /> * loader - this component handles the loading of all other kickstart modules<br /> * battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time<br /> * bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS<br /> * bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS<br /> * con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface<br /> * console.device.kmod - it opens a window and reads/writes text to and from that window<br /> * diskboot.kmod - handles the booting of AmigaOS from a supported disk<br /> * diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS<br /> * dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories<br /> * elf.library.kmod - handles the loading of executable programs<br /> * env-handler.kmod - handles the read/writes of environment variables<br /> * FileSystem.resource.kmod - handles the use of the different filesystems<br /> * gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...<br /> * gameport.device.kmod - handles the read/writes of game pads and joysticks<br /> * graphics.library.kmod - collection of functions used to draw graphic elements on the monitor<br /> * hunk.library.kmod - set of functions to read a data stream into memory<br /> * input.device.kmod - handles of input events like keyboard events or mouse clicks<br /> * intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)<br /> * layers.library.kmod - set of functions to be used to handle different layers in graphic operations<br /> * keyboard.device.kmod - driver for the keyboard<br /> * keymap.library.kmod - functions to handle different keymaps<br /> * newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )<br /> * nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage<br /> * nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers<br /> * PCIGraphics.card - driver that supports the use of different graphic cards<br /> * ram-handler.kmod - functions that handles the '''Ram disk:''' special disk<br /> * ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk<br /> * ramlib.kmod - loads disk based libraries and devices for exec.library<br /> * rtg.library - library of functions perform lowlevel graphic operations on graphic cards<br /> * shell.kmod - the AmigaOS command line interface<br /> * strap.kmod - module that handles booting on different disk devices<br /> * timer.device.kmod - driver to give access to timing functions<br /> <br /> === Filesystem support ===<br /> <br /> These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.<br /> <br /> * CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...<br /> * SmartFilesystem - allows to store data on partitions in SFS0 and SFS2<br /> * JXFileSystem - allows to create partitions in JXFS<br /> * FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts<br /> * diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules<br /> <br /> === Hardware drivers ===<br /> <br /> ==== Graphic cards drivers ====<br /> <br /> * 3dfxVoodoo.chip<br /> * 3DLabsPermedia2.chip<br /> * ATIRadeon.chip<br /> * RadeonHD.chip<br /> * siliconmotion502.chip<br /> <br /> ==== Disk drivers ====<br /> <br /> Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.<br /> <br /> * it8212ide.device.kmod<br /> * lsi53c8xx.device.kmod<br /> * sam460sata.device.kmod<br /> * sii3112ide.device.kmod<br /> * sii3512ide.device.kmod<br /> * sii3114ide.device.kmod<br /> * sii0680ide.device.kmod<br /> * sii3132ide.device.kmod<br /> <br /> ==== USB drivers ====<br /> <br /> * hub.usbfd<br /> * usbsys.device<br /> * usbresource.library<br /> * ehci.usbhcd<br /> * ohci.usbhcd<br /> * uhci.usbhcd<br /> * massstorage.usbfd<br /> <br /> ==== Other drivers ====<br /> <br /> * bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded<br /> * bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded<br /> * fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers<br /> * i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers<br /> * xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000<br /> <br /> === Misc modules ===<br /> <br /> * petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor<br /> <br /> == System components ==<br /> <br /> [[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]<br /> <br /> Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.<br /> Here is described a default AmigaOS installation.<br /> <br /> * C<br /> This directory contains AmigaDOS '''C'''ommands<br /> * Classes<br /> contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...<br /> * Devs<br /> contains definition for '''Dev'''ices<br /> * Emulation<br /> contains files used for the 68k emulation (though E-UAE)<br /> * Fonts<br /> contains various systems fonts<br /> * Internet<br /> contains a dialer to connect to Internet<br /> * Kickstart<br /> contains the kickstart modules<br /> * L<br /> contains hand'''l'''ers and filesystems<br /> * Libs<br /> contains dynamic '''Libr'''airies of functions<br /> * Locale<br /> contains all files used to localise the system (catalogs, keymaps...)<br /> * MUI<br /> contains the needed files for programs that use the MUI third party graphic interface<br /> * Prefs<br /> contains the preference programs used to customise AmigaOS<br /> * S<br /> contains the '''S'''cripts<br /> * SObjs<br /> contains .so shared object library files<br /> * Storage<br /> contains other optional files<br /> * System<br /> contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools<br /> * Utilities<br /> contains several utilities<br /> <br /> = Motorola 680x0 Emulators =<br /> <br /> For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.<br /> <br /> In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be &quot;switched off&quot;.<br /> <br /> Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. &quot;Native&quot; PowerPC programs were rare, and every time a PowerPC program called the system, a so called &quot;context switch&quot; occurred between the 680x0 and PowerPC code, often causing a large performance penalty.<br /> <br /> The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor. <br /> <br /> == Two 680x0 Emulators ==<br /> <br /> In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low &quot;reaction time&quot;, and is ideal for time critical parts, such as interrupts.<br /> <br /> The other is Petunia, the &quot;JIT emulator&quot;. A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.<br /> <br /> Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, &quot;on the fly&quot;.<br /> <br /> This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.<br /> <br /> == Features ==<br /> <br /> Emulated opcodes:<br /> * all user and supervisor level opcodes of the Motorola 68040<br /> * all FPU opcodes of the Motorola 68881/68882 <br /> <br /> AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.<br /> <br /> At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.<br /> <br /> == Removing the JIT Emulator ==<br /> <br /> Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.<br /> <br /> If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.<br /> <br /> Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the &quot;Sys:Kickstart/Kicklayout&quot; file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like &quot;DefaultJIT&quot;, or &quot;DefaultNoJIT&quot;.<br /> <br /> == Configuring the Emulators ==<br /> <br /> Petunia cooperates with a so called &quot;black list&quot;. By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.<br /> <br /> If an executable needs to be added to the list, then it can be done by extending the file &quot;DEVS:applications.dos&quot; with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.<br /> <br /> Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.<br /> <br /> Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.<br /> <br /> For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list. <br /> <br /> = AmigaOS boot procedure =<br /> <br /> Basically a computer with AmigaOS does the following when the power button is pushed:<br /> <br /> * [[File:Uboot.jpg|200px]]<br /> the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.<br /> * depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.<br /> * [[File:SLB.png|200px]]<br /> the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.<br /> The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.<br /> * [[File:Kmods loading.png|200px]]<br /> the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module<br /> * '''Loader''' executes the kickstart modules (Exec, devices, libraries...)<br /> * AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor<br /> * the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume<br /> * the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.<br /> * the Workbench is started<br /> <br /> At this point the user can use his/her computer.<br /> <br /> = How to make a Bootable USB Memory Stick for AmigaOS 4.1 =<br /> <br /> By Julian Margetson (&quot;Spectre660&quot;)<br /> <br /> Prerequisites:<br /> * USB memory stick of 2 GB or less in size.<br /> * It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.<br /> * Plug the USB memory stick into a USB port on your machine.<br /> * Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.<br /> <br /> Procedure:<br /> # You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.<br /> # Make certain that you have selected usbdisk.device and not any other device.<br /> # Click on &quot;Start&quot;<br /> # You will see the usb mass storage unit connected in a list.<br /> # Make sure that the Unit type displayed for the USB memory stick is &quot;Removable hard disk&quot;<br /> # Select that Unit by clicking on it.<br /> # The first thing that you need to do is to install the RDB onto the USB Memory Stick.<br /> # Click on the &quot;Install&quot; button.<br /> # A window Labeled &quot;RDB/disk geometry editing&quot; comes up.<br /> ## Towards the bottom of the window is the &quot;AmigaOne boot code (SLB)&quot; section.<br /> ## Select the &quot;Install&quot; button .<br /> ## A file requester &quot;Select AmigaOne Boot Code&quot; now comes up with the Drawer choice defaulting to &quot;l:&quot;<br /> ## Select file &quot;slb_v2&quot;. <br /> ## Select Ok.<br /> ## You are now returned to the &quot;RDB/disk geometry editing window&quot;.<br /> ## Select &quot;Ok-accept changes&quot;.<br /> # You are now returned to the display showing the attached USB unit.<br /> # Select &quot;Edit partitions and Filesystems&quot;. You will now see the Window 'Editing partitions for disk&quot;<br /> # Select &quot;Add partition&quot;<br /> # This defaults to using the whole device as a single partition.<br /> # It is possible to use create more partitions but for this tutorial we will only use one.<br /> # You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the &quot;Name&quot; box.<br /> # Now make sure that the Boxes &quot;Automount&quot; and &quot;Bootable&quot; are selected and show the &quot;Tick mark&quot;.<br /> # You need to set &quot;Boot priority&quot; to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the &quot;+&quot; to the right of the &quot;boot priority&quot; box. Normally you can set the boot priority to 2 .<br /> # Next it is time to select the file system to use.<br /> # Select &quot;Select filesystem/edit details&quot;.<br /> # The Window &quot;Editing details for partition 'USB0'&quot; ,or whatever partition name you used, comes up.<br /> ## Select the file system that you are going to use by selecting the pull down menu under &quot;Filesystem chooser&quot;.<br /> ## Only filesystems SFS/00 or SFS/02 will work for a bootable device.<br /> ## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.<br /> ## Next select Blocksize from the &quot;Blocksize&quot; pull down menu. 512 is the correct size to use.<br /> ## Now Select &quot;Ok-accept changes&quot;.<br /> ## Your are now returned to the &quot;Edit partitions for disk&quot; window.<br /> ## Again select &quot;Ok-accept changes&quot;<br /> # You are now returned to the window showing the USB mass storage unit list.<br /> # Select &quot;Save to disk&quot;<br /> # A requester pops up with the options &quot;Yes, Save.&quot; or &quot;No!&quot;<br /> # Select the &quot;Yes, save.&quot; option.<br /> # You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.<br /> # This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.<br /> # Select &quot;Yes, reboot NOW!&quot;.<br /> # Once you have rebooted connect your USB Memory Stick to a USB port.<br /> # A disk icon &quot;USB0:Uninitialized&quot; (or whatever partition name you used) appears on Workbench.<br /> # You now need to format the device.<br /> # To format Select this Icon and go to the Workbench &quot;Icons&quot; menu .<br /> # Select &quot;Format Disk&quot;<br /> # You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.<br /> # You can use either a full Format or a Quick Format. Full Format may take a few minutes.<br /> # Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=AmigaOne_500&diff=7257 AmigaOne 500 2014-02-21T20:44:31Z <p>Philippe Ferrucci: </p> <hr /> <div>The AmigaOne 500 is a PowerPC-based mid-range computer available for AmigaOS.<br /> <br /> = Key Specifications =<br /> <br /> * FlexATX form factor (21.6 x 17 cm)<br /> * Applied Micro PPC460ex SoC – upto 1.10 Ghz<br /> * max 2 GB DDR2 Ram – 200-pin SODIMM<br /> * Silicon Motion SM502 embedded MoC (audio/video) max 64MB Gfx RAM<br /> * Audio 5.1 Realtek ALC655 codec<br /> * PCI-express 4x lanes slot (16x mechanical connector)<br /> * PCI-express 1x lane slot (mutually exclusive with the SATA port)<br /> * PCI slot, 32 bit, 33 Mhz, 3.3V<br /> * 1x SATA2 port (mutually exclusive with the PCIe 1x slot)<br /> * 6x USB2 EHCI/OHCI ports + 1 USB 1.1 port<br /> * 1x 10/100/1000 Ethernet port<br /> * Lattice XP2 FPGA with 80 I/O pins expansion connector<br /> * integrated SD card reader<br /> * RTC clock<br /> * Serial port, 8-wires<br /> * I2C and SPI/I2C buses<br /> <br /> = Manufacturer =<br /> <br /> [http://www.acube-systems.com ACube Systems] is the manufacturer of the Sam460 motherboard which is inside the AmigaOne 500.<br /> <br /> Check the [http://www.acube-systems.biz/index.php?page=resellers ACube Systems resellers] page to find your AmigaOne 500.<br /> <br /> = Frequently Asked Questions =<br /> <br /> == What is the difference between AmigaOne 500 and Sam460? ==<br /> <br /> The AmigaOne 500 is a complete system, ready to go, like the old Amiga was. It is based on the Sam460 motherboard. You can purchase the later alone if you prefer to use another case or other peripherals.<br /> <br /> == How to use more than one SATA drive? ==<br /> <br /> The Sam460ex is made both for embedded and consumer markets. It can be adapted to different needs. As an example, a customer who wants a board for home use will probably choose to add a SATA controller on a PCI card. This will allow up to four SATA drives. ACube may provide such expansion boards.<br /> <br /> == How can the operating system be loaded? ==<br /> <br /> It is possible to load the operating system from a SATA harddisk, a CDROM connected on SATA, a USB key, a SD card or from the network.<br /> <br /> == Which setup are possible with the board? ==<br /> <br /> It's possible to use the Sam460ex in one of these setup:<br /> * PCI-Express 16x slot + PCI slot + PCI-Express 1x slot<br /> * PCI-Express 16x slot + PCI slot + SATA2 port</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=AmigaOne_500&diff=7251 AmigaOne 500 2014-02-19T23:20:11Z <p>Philippe Ferrucci: Created page with &quot;The AmigaOne 500 is a PowerPC-based mid-range computer available for AmigaOS. = Key Specifications = * FlexATX form factor (21.6 x 17 cm) * Applied Micro PPC460ex SoC – up...&quot;</p> <hr /> <div>The AmigaOne 500 is a PowerPC-based mid-range computer available for AmigaOS.<br /> <br /> = Key Specifications =<br /> <br /> * FlexATX form factor (21.6 x 17 cm)<br /> * Applied Micro PPC460ex SoC – upto 1.10 Ghz<br /> * max 2 GB DDR2 Ram – 200-pin SODIMM<br /> * Silicon Motion SM502 embedded MoC (audio/video) max 64MB Gfx RAM<br /> * Audio 5.1 Realtek ALC655 codec<br /> * PCI-express 4x lanes slot (16x mechanical connector)<br /> * PCI-express 1x lane slot (mutually exclusive with the SATA port)<br /> * PCI slot, 32 bit, 33 Mhz, 3.3V<br /> * 1x SATA2 port (mutually exclusive with the PCIe 1x slot)<br /> * 6x USB2 EHCI/OHCI ports + 1 USB 1.1 port<br /> * 1x 10/100/1000 Ethernet port<br /> * Lattice XP2 FPGA with 80 I/O pins expansion connector<br /> * integrated SD card reader<br /> * RTC clock<br /> * Serial port, 8-wires<br /> * I2C and SPI/I2C buses<br /> <br /> = Manufacturer =<br /> <br /> [http://www.acube-systems.com ACube Systems] is the manufacturer of the Sam460 motherboard which is inside the AmigaOne 500.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=UserDoc:Main&diff=7249 UserDoc:Main 2014-02-19T19:52:06Z <p>Philippe Ferrucci: /* AmigaOS platform targets */</p> <hr /> <div>== Welcome to AmigaOS ==<br /> <br /> AmigaOS was born in 1985 and delivered what contemporary personal computer operating systems could only dream of. As the first &quot;multimedia&quot; operating system, it was trivial for AmigaOS computers to display animations while playing music and reading data from disks. Such multimedia and multitasking finesse drew many people to this system. Some of them are famous: [http://www.amigahistory.co.uk/warhol.html Andy Warhol], Sir Arthur C. Clarke, [http://www.polyphoto.com/upchug/AEcastro.html NASA], Hollywood and the TV broadcasting industry, and many others that thought [http://www.youtube.com/watch?v=PWeO5IkCssk only Amiga makes it possible].<br /> <br /> Today many people still think AmigaOS has something special that makes it more interesting and rewarding than other systems. This system allows the user to control the computer, not the other way around. It is a system you fully understand that is easier and more flexible to use. In other words, AmigaOS is '''more fun'''.<br /> <br /> === AmigaOS: The flexible operating system ===<br /> AmigaOS is an operating system: a collection of efficient programs written to start the computer, let the user control the computer, and present feedback to the user.<br /> <br /> AmigaOS is designed with ease of use and flexibility in mind. To begin with, AmigaOS provides a clear view of your computer, your applications and files. A number of methods are available to let your computer serve you, whether graphically with a mouse, using the &quot;Shell&quot; command line, or by some other means the user prefers.<br /> <br /> AmigaOS strives to avoid stupid limitations that can be found on other systems. AmigaOS users can organise their files the way they like. There are few limits on file hierarchy, locations and file names. Drives don't have to be named with a letter or cryptic names (such as C:, or sda1), your files don't have to reside in your &quot;Documents&quot; folder and your hard drives aren't hidden from you. If you're not writing to drives and you want to &quot;shut down&quot;, why wait for the OS to allow that? With AmigaOS, just hit the power switch. Done.<br /> <br /> An Amiga does not start with pre-installed applications serving some sales conglomerate, marketing organization or their big brother. AmigaOS does not do actions behind the user's back. As unique as it is today, the AmigaOS computer serves the user and not the other way around. With one of the largest proportions of user-programmers around, the trustworthy AmigaOS user-friendly ethic is mirrored in AmigaOS applications.<br /> <br /> Since the first versions more than twenty-five years ago, AmigaOS has also been designed to serve efficiently. Optimizing applications and OS code has always been the goal of programmers and developers of this operating system. The result is an operating system and applications that take less space on your hard drives, waste less time loading, consume less memory, require less processing power, and respond more quickly to the user.<br /> <br /> And every update of AmigaOS doesn't demand you must buy newer, more powerful hardware. AmigaOS currently runs on twenty year old 200MHz computers or brand new dual core 1,800MHz computers. It's the user's choice how they want to '''enjoy''' AmigaOS.<br /> <br /> === Some AmigaOS features ===<br /> Here are some of the features of AmigaOS that make it easy to control your computer. Some of these concepts were copied by other operating systems which tend to show they are the correct way of doing things.<br /> <br /> * '''Small footprint:''' AmigaOS can work with 64 MB of memory. On disk, a default installation only takes around 200 MB. The smaller footprint translates into a more responsive user experience given any hardware.<br /> <br /> * '''Straightforward operating system design:''' With a clear layout and easy to understand names (Classes, Libs, Fonts, Prefs, Storage, etc.), you can easily understand what everything in AmigaOS is and what it does for you. Nothing is hidden from the user and the user is not restricted by AmigaOS.<br /> <br /> *'''User configurable graphic interface:''' Using the provided &quot;preferences editors,&quot; the user can dramatically reconfigure how AmigaOS looks, sounds, runs and responds to every user whim.<br /> <br /> * '''File recognition based on file content:''' You can name a file '''whatever you want''', even without an extension. Examples: &quot;my file&quot; or &quot;picture of Jay in Santa Clara&quot;. There is no need to add an extension to explain what the file is, like &quot;.txt&quot; or &quot;.jpg&quot;. AmigaOS really examines the '''file content''' to recognise what type of file it is. <br /> <br /> * '''Logical assignments:''' Easily set and use logical names names for directories located anywhere on your system. For example, &quot;Auto:&quot; can point to your directory &quot;car show pictures&quot; buried on your media drive.<br /> <br /> * '''Ram disk concept:''' On AmigaOS there is a special disk called the '''Ram disk''' which represents a part of your computer memory. This area is not fixed. It automatically grows whenever you store files in it. For example, it's a great place to unpack files to install from there, greatly speeding up the installation.<br /> <br /> * '''Command line and graphical user interfaces:''' Both the the graphical user interface (GUI) and command line interface (where you type commands into a window with the keyboard) can be used to manage AmigaOS, its programs and files. Both interfaces are intergated with each other so you can easily use command lines from the GUI or open graphical elements from a command line.<br /> <br /> *'''ARexx Ports:''' Throughout AmigaOS and third party programs, &quot;ARexx&quot; message ports let one application talk with others so that apps work together to serve the user. AmigaOS also provides the lightweight ARexx and modern Python programming languages that can control AmigaOS and applications with ARexx ports.<br /> <br /> * '''Resident Commands:''' Commands can be made resident, i.e., they are kept in memory so that they can be reused with no loading time.<br /> <br /> * '''Restart only the operating system:''' if you feel the need to restart the system, you can do so by restarting '''only AmigaOS''' and not the whole computer.<br /> <br /> === AmigaOS platform targets ===<br /> <br /> While the original versions of AmigaOS ran on computers of the eighties using Motorola 68k series CPU chips, the current AmigaOS runs on computers using PowerPC processor chips [http://www.amigaos.net/content/72/supported-hardware hardware]. These can be older Amiga computers (also called &quot;Classic Amigas&quot;) with PPC &quot;accelerator cards&quot; or new generation Amiga PPC computers. <br /> <br /> In this guide, we will concentrate on the current AmigaOS running on the supported hardware.<br /> <br /> [[AmigaOne X1000]] by [http://www.a-eon.com A-Eon Technology]<br /> <br /> [[AmigaOne 500]] and Sam460 by [http://www.acube-systems.com ACube Systems]<br /> <br /> [[Pegasos II]] by [http://www.bplan-gmbh.de bplan GmbH]<br /> <br /> == How does AmigaOS work? - Concepts ==<br /> <br /> In this page we will discuss [[UserDoc:How AmigaOS Works|how AmigaOS works]]:<br /> <br /> * [[UserDoc:How_AmigaOS_Works#The_most_important_components|The most important components]] (Exec, AmigaDOS, Intuition...)<br /> * [[UserDoc:How_AmigaOS_Works#How_is_my_data_stored.3F|how files and data are stored]]<br /> * [[UserDoc:How_AmigaOS_Works#All_AmigaOS_components|all AmigaOS components are described]]<br /> * [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|how AmigaOS is booted on your Amiga computer]]<br /> * AmigaOS settings programs<br /> * ...<br /> <br /> == How to use AmigaOS? ==<br /> <br /> AmigaOS is a collection of components that oversee the computer hardware &amp; data and provide the user with easy, understandable tools to manage and use them.<br /> <br /> In the following [[UserDoc:Introduction to AmigaOS|Introduction to AmigaOS pages]] we will discuss the basic concepts:<br /> <br /> * how to use AmigaOS<br /> * what the AmigaOS graphic user interface is composed of <br /> * what interfaces AmigaOS provides, including the [[UserDoc:Workbench|Workbench]], the [[UserDoc:Shell|Shell]] or scripting languages.<br /> <br /> From the introduction page, you can continue with more detailed pages on the [[UserDoc:Workbench|Workbench]] and the [[AmigaDOS manual]] . Now let's start with this [[UserDoc:Introduction to AmigaOS|Introduction to AmigaOS]].<br /> <br /> == Manuals ==<br /> <br /> [[AmigaOS Manual]] - AmigaOS Manual<br /> <br /> [[Bars &amp; Pipes Professional]] - MIDI Sequencer</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=UserDoc:Introduction_to_AmigaOS&diff=6653 UserDoc:Introduction to AmigaOS 2013-10-18T14:27:58Z <p>Philippe Ferrucci: /* Scripts &amp; Messages */</p> <hr /> <div><br /> Like any modern personal computer system, AmigaOS presents a graphic interface and relies on common peripherals to let the user control their system. <br /> Beyond most systems, AmigaOS provides more flexibility and options in how the user can approach, configure and use their Amiga computer.<br /> <br /> In this page we will describe the details of AmigaOS graphic user interface (GUI) - how screens, windows and gadgets are presented and how you can use them.<br /> We will also describe the various means by which the user can control and operate AmigaOS. In additional pages, you can read about [[UserDoc:How AmigaOS Works|how AmigaOS works]] and what its components are.<br /> <br /> == AmigaOS Input - Point, Click and Type ==<br /> <br /> There are two common ways you can use and control your AmigaOS system - by mouse and keyboard. <br /> <br /> But AmigaOS also lets you control your system by other input devices (like touchscreens or voice recognition) depending on drivers and devices connected. Depending on software installed, AmigaOS can also be remotely controlled by networked protocols (like VNC and Synergy). Finally, AmigaOS can be controlled internal scripts set up by the User.<br /> <br /> === Using the mouse ===<br /> <br /> [[File:Style2.5.png|frame|right]]<br /> <br /> Typically in AmigaOS, you use a mouse to act on graphic elements (like &quot;gadgets&quot;, &quot;icons&quot; or webpage &quot;links&quot;). By default, AmigaOS expects and supports mice or trackball pointing devices with at least two buttons. The left mouse button is used to &quot;left-click&quot; on graphic objects, to select them or operate them. The right mouse button is used to &quot;right-click&quot; and display the menus of the current application.<br /> <br /> Optionally, one can use a mouse or trackball device with three (a &quot;middle&quot; button) and four buttons. With such devices, the functionality of the additional buttons can vary by application or environment. These functionalities can typically be configured by the user in specific applications or within AmigaOS (globally).<br /> <br /> Furthermore, scroll wheels are supported by AmigaOS in a context-based fashion. If the current application's window is scrollable, the scrollwheel will act on that area. If the mouse pointer is positioned over a specifically scrollable gadget, the scrollwheel will affect that gadget.<br /> <br /> In some applications and environments, you can also &quot;double-click&quot; (click twice, quickly) with the left button on an object to engage them. In the Workbench file manager, a single mouse click will only &quot;select&quot; an icon, whereas a double-click will open drawer/directory, run an application or open a file in an associated program.<br /> <br /> Beside &quot;clicking&quot; - pressing down and releasing a mouse button at a specific location - you can also perform what is known as &quot;dragging&quot;, which means clicking down and then moving the mouse around before releasing the mouse button. This is typically always done with the left mouse button and is done to select objects (draw a box around them), to adjust a control slider or to resize a window.<br /> <br /> &lt;br style=&quot;clear: both&quot; /&gt; <br /> <br /> === Using the keyboard ===<br /> <br /> Of course the keyboard is used to enter text into text editing areas. But your keyboard can do so much more with its special &quot;qualifier&quot; keys and AmigaOS.<br /> <br /> The most common example of a qualifier key is the &quot;Shift&quot; key which causes typed text to be made upper-case or capitalized. There are more qualifier keys on most keyboards, here is a list of all of them:<br /> * '''the Shift keys''' - the common key that causes your text to be capitalized.<br /> * '''The &quot;Alternate&quot; keys''' - the &quot;Alt&quot; keys typically to the bottom right and left of the keyboard.<br /> * '''the &quot;Control&quot; keys''' - the &quot;Ctrl&quot; keys also to the bottom right and left of the keyboard.<br /> * '''the &quot;Amiga&quot; keys''' - special &quot;A&quot; keys on the right and left side of the space bar. Besides being unique to AmigaOS, the right and left Amiga keys always mean different things (unlike the rest of the qualifier keys, most of the time). If you have a non-AmigaOS keyboard, the &quot;Windows&quot; or MacOS &quot;Command&quot; keys function as &quot;Amiga&quot; keys.<br /> ** '''the Right Amiga key''' - is used for &quot;short cuts&quot; within your current application.<br /> ** '''the Left Amiga key''' - is used for &quot;short cuts&quot; that are globally active anytime and anywhere in your AmigaOS system.<br /> While all of these qualifier keys don't usually do anything on their own, when you press and hold one or more of these keys down while pressing regular keys, they can change what you type (capitalizing or making alternate characters) or become powerful &quot;short-cuts&quot; within your applications or throughout your entire AmigaOS system.<br /> <br /> The most famous short-cuts are the '''copy''', '''cut''' and '''paste''' operations that you can perform on selected text:<br /> * the '''Right-Amiga C''' short-cut copies any selected text or content to the Clipboard.<br /> * the '''Right-Amiga X''' short-cut &quot;cuts&quot; any selected text or content to the Clipboard.<br /> * the '''Right-Amiga V''' short-cut &quot;pastes&quot; any text or content from the Clipboard into your application (at the current cursor location).<br /> <br /> == The AmigaOS GUI - Intuition ==<br /> <br /> When AmigaOS has started, you will typically see the Workbench file manager. This is the start of your experience with the AmigaOS GUI and it's most basic elements: a screen with menus and windows containing icons and &quot;gagdets&quot;. These components are the basic building blocks of virtually all AmigaOS &amp; application interfaces.<br /> <br /> As with most things in AmigaOS, almost all of the following components can also be almost infinitely reconfigured, adjusted and graphically varied by the user. In the AmigaOS &quot;Preferences&quot; drawer, the &quot;GUI&quot;, &quot;ASL&quot;, &quot;Locale&quot;, &quot;Font&quot;, &quot;Palette&quot;, &quot;Poiner&quot;, &quot;PopUpMenu&quot;, &quot;Screens&quot;, &quot;Workbench&quot; and &quot;WBPattern&quot; preferences editors easily allow a user to reconfigure the GUI of their Amiga in drammatic ways.<br /> <br /> AmigaOS also supports the use of alternate GUI systems in parallel with the default &quot;Intuition&quot; (aka &quot;Reaction&quot;) GUI system. By default AmigaOS also comes with the &quot;Magic User Interface system (&quot;MUI&quot;, a variant of the basic AmigaOS GUI system. More than Intuition, MUI can be reconfigured even more widely using its own MUI configuration app. <br /> <br /> Additionally, AmigaOS can use a number of third-party &quot;cross-platform&quot; GUI systems: &quot;AmiCygnix&quot; GUI system - a native X11 GUI implementation for AmigaOS - and a native port of the &quot;Qt&quot; GUI system. With either of these systems, it is possible to run ported applications compiled for AmigaOS, but running with these cross-platform GUI systems.<br /> <br /> To start with, we will explore the elements that make up the AmigaOS GUI system.<br /> <br /> === Screens ===<br /> <br /> As start-up, the Workbench will be running on its &quot;Workbench Screen&quot;. This will be the default location where most other application windows will also appear when started.<br /> <br /> Typically an AmigaOS screen will have a &quot;title bar&quot; across the top with a graphical &quot;depth gadget&quot; at the right end. In the case of the Workbench screen,<br /> there will be an AmigaOS &quot;boing ball&quot; at the left end and the title bar will display certain system information (OS version, memory availability, etc.). Within the screen, the Workbench and any other applications can open windows, display icons and other GUI devices. If you right-click over the title bar, it becomes a &quot;Menu Bar&quot;, showing you the control menus that are available for that application.<br /> <br /> In many cases, other applications may open screens in addition to the Workbench screen. The &quot;depth gadget&quot; at the right end of each screen's title bar allows you to click from screen from screen. Besides clicking on the screen's depth gadet, AmigaOS also lets the user see other screens behind the front screen by &quot;dragging' down on the screen title bar.<br /> <br /> The characteristics of the Workbench screen such as resolution and color depth can be configured in the &quot;Screenmode&quot; preferences editor. Other screens can be either be configured in the &quot;Screens&quot; preferences editor or from within individual applications. Typically, AmigaOS applications also give the user the choice of whether application runs on their own screens or the &quot;public&quot; Workbench screen.<br /> <br /> === Windows ===<br /> Windows are graphic containers that appear within AmigaOS screens. Windows can be created by any number of different applications - the Workbench, Shell sessions or applications. Outside of the Workbench file manager, each window usually reflects each individual running application. In some cases, one application may open multiple documents in separate windows or additional &quot;requester&quot; windows might appear for an application.<br /> <br /> [[File:LibFig4-1.png]]<br /> <br /> Almost all windows of AmigaOS will have these common elements:<br /> * '''Borders''' - A border around the window's contents. Holding the Shift+Left-Amiga keys down while dragging any border will drag the window around. <br /> * '''Title bar''' - A thicker top border that typically contains a name of the application or it's contents. The area of the title bar acts as a &quot;drag bar&quot; which you can use to drag the window around the screen.<br /> * '''Depth gadget''' - The right-most gadget in the top title bar that either pulls the window to front (if it isn't frontmost) or pushes it to the back (if it's in front). Holding down the Shift key while clicking this gagdet pushes the window to the back.<br /> <br /> In AmigaOS, windows may also optionally have these additional features and elements:<br /> * '''Close gadget''' - The left-most gadget in the title bar that closes the window.<br /> * '''Scroll bar(s) and arrows''' - If the contents of the window can be scrolled in vertically and/or horizontally, there will be a scroll bar with arrow scroll buttons. These scroll bars can also be used if the mouse pointer is over a scroll bar and the mouse scroll wheel is used.<br /> * '''Zoom gadget''' - the second gadget from the right-most of the title bar which switches the window between two sizes. Holding down the Shift key while clicking this gadget will make it fill the screen.<br /> * '''Iconification gadget''' - left-most of the right-hand gadgets in the title bar which causes the window to disappear into an icon on the Workbench background - thus &quot;Iconifying&quot; the window or application.<br /> * '''Sizing gadget''' - In the case of windows that can be resized, this is the gadget in the bottom right corner of the window that you can drag to resize the window.<br /> <br /> Each AmigaOS application can use almost infinite combinations of these features in the make up of their windows.<br /> <br /> === Menus ===<br /> <br /> [[File:LibFig2-4.png|frame|right]]<br /> Menus are lists of items that will allow you to see and use what commands are available in an application. The Workbench uses menus you can use to perform actions on the Workbench and its contents. Menus typically provide many more functions and commands than can be presented to the user than just graphic buttons, etc. within an application's window, as a result they are a primary way most applications are used.<br /> <br /> In AmigaOS menus can always be found for the current application by moving the mouse to the top of the screen and right-clicking. The screen title bar will become a menu bar and will show the names of all the current application's menus. <br /> <br /> By dragging with the right mouse button, each menu will display its &quot;menu items&quot;. Each of those menu items corresponds to a command or setting. In some cases you will find a &quot;check box&quot; on a menu item which you can click on to toggle a setting. In other cases, you will find that menu items have a little arrow head that indicates that item actually has a &quot;sub-menu&quot; - a menu within a menu. Menus ending with ellipses (&quot;...&quot;) indicate that menu item will open a window that can be cancelled without commiting any command. For those menu items that might be deactivated (they may not apply at the moment), they will be &quot;greyed-out&quot;.<br /> <br /> The labels of many menu items will also include a letter or two with an &quot;A&quot; at the right edge. This indicates what the keyboard Right-Amiga &quot;short cut&quot; is the equivalent of using that menu item within that application. In the above screen shot, you can see that pressing the two keys - &quot;Right-Amiga&quot; and &quot;N&quot; - would do the same as that menu item - to create a new drawer.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> <br /> ====Consistent Organization====<br /> For the sake of consistency (when applicable), the first two AmigaOS menus of any application are typically organized with the following hierarchy and use these keyboard equivalents:<br /> <br /> {| border=&quot;0&quot;<br /> |'''First Menu:'''<br /> ----<br /> || || Keyboard equivalent: || '''Second Menu:'''<br /> ----<br /> || || Keyboard equivalent:<br /> |-<br /> |'''PROJECT'''<br /> ----<br /> || || ||'''EDIT'''<br /> ----<br /> || <br /> |-<br /> |'''New'''|| = Create new project in application.||Right-Amiga N||'''Cut'''|| = Cut the selected content into the Clipboard.||Right-Amiga X<br /> |-<br /> |'''Open...'''|| = Open the file containing a project.||Right-Amiga O||'''Copy'''|| = Copy the selected content into the Clipboard.||Right-Amiga C<br /> |-<br /> |'''Save'''|| = Save the project to it's current file name.||Right-Amiga S||'''Paste'''|| = Paste the Clipboard contents into the project (at the current location).||Right-Amiga V<br /> |-<br /> |'''Save As...'''|| = Save the project to a file of a new name.|| ||'''Undo'''|| = Undo the last change to current project.||Right-Amiga Z<br /> |-<br /> |'''Print'''|| = Print the current project.||Right-Amiga P||'''Redo'''|| = Restore the last change &quot;undone&quot; in the current project.|| <br /> |-<br /> |'''Close'''|| = Close the project.|| || || || <br /> |-<br /> |'''Quit'''|| = Quit the application.||Right-Amiga Q|| <br /> |}<br /> <br /> ====Menu Variations====<br /> AmigaOS also includes a couple additional ways menus can be can serve the user:<br /> <br /> =====Pop-Up Menus=====<br /> <br /> [[File:OS4-WBPopUpMenu.jpg|frame|right]]<br /> In the GUI preferences editor you can configure menus to &quot;pop-up&quot; under the mouse pointer whenever you right-click the mouse. This means you do not need to move the mouse to the top of the screen to use the menus. There are also options for making menus &quot;sticky&quot;, meaning that you don't need to drag the mouse to navigate the menus, but rather just right click and the menus stay open till you make a selection or click away.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> <br /> =====Context Menus=====<br /> <br /> [[File:OS4-WBContextMenu.jpg|frame|right]]<br /> The Workbench (with a utility added by default) and many applications provide &quot;contextural menus&quot;. This means that you can put your mouse pointer over elements and right-click to pop-up a menu of things that are specific to the item you clicked over. In the case of the Workbench (with the Context Menus utility), right clicking on a file will pop-up a menu of things that could be done with that file, like deleting it.<br /> <br /> All of these features provide both a simple means of using many functions within an application and at the same time allowing the user to configure a very efficient user interface that responds to nearly every whim.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> <br /> === Icons ===<br /> <br /> ==== Description ====<br /> Icons are small images which can represent a disk, a directory, an application file or data file. Icons are primarilly used within the AmigaOS Workbench environment to represent all the file system objects the user can manipulate. With these icons it is possible to select files, open them, delete them or move them around within the Workbench. Applications may also make more limited use of icons to represent file system objects or may be used as imagery in an &quot;icon bar&quot; of buttons that can be clicked to perform various actions represented by icon imagery, like the Clock above.<br /> <br /> {|style=&quot;text-align: center;&quot;<br /> |[[File:LibDiskIcon.png|frame|left|100px|Drive icon]] [[File:Icons.png|frame|right|Directory with sub-directory, data and application file icons]]<br /> |}<br /> <br /> AmigaOS also uses different icon imagery to indicate various types of icons - drives, directories, files and applications. Drive or partition icons look like little hard drives. <br /> A directory icon will look like a cabinet &amp; drawer whereas a file icon will be designed to give a clue about the file content.<br /> Data files are normally shown with a &quot;page&quot; motif and some graphics or text to reflect the file type.<br /> Application files typically have the most free-form graphics that reflect their purpose, name or developer.<br /> <br /> The user can also edit the icon imagery using the icon editor, change how icons react to being double-clicked and adjust parameters stored within the icon file that affect how the represented file will be used.<br /> <br /> Many applications and all AmigaOS file requesters allow Workbench icons to be &quot;dragged and dropped&quot; into the application or requester windows and the associated file will be recognized by the application, if possible.<br /> <br /> ==== Icon states ====<br /> <br /> Icons can look different not only because of their image but also depending on their state. <br /> <br /> As you can see in the directory example, the 2 top left icons appear semi-transparent. This subtle difference reflects whether the file or directory has an associated icon file with it. In AmigaOS, any directory or file can have such an icon file that stores a unique icon image, unique program settings or specific settings for that file or directory. That information can be adjusted within the Workbench and is automatically stored in a companion file with the same name, but with an added '''.info''' suffix. <br /> <br /> While many files &amp; directories and most applications have such &quot;.info files&quot; with them, they are not required and the Workbench can be set to show you &quot;default icons&quot; (based on the file types, etc.) so you can manipulate the corresponding objects. Of course, AmigaOS can also be configured on a directory-by-directory basis to only show files that have associated &quot;.info&quot; files.<br /> <br /> In the same picture, the 2 top right directory icons also look slightly different. While the '''Utilities selected''' and the '''Utilities unselected''' are the same icon, their image is a bit different. The drawer of the first one is slightly opened and there is a &quot;glow&quot; effect arround the first icon. These two visual clues show you the first directory icon has been selected by the user whereas the second one is not.<br /> <br /> ==== App Icons ====<br /> <br /> Many applications provide the option to be &quot;iconified&quot; either by clicking on an iconification gadget in their window title bars or by menu item. In those events, the application's window will disappear and an &quot;app icon&quot; will appear on the background of the Workbench screen. Double-clicking on the app icon will cause the icon to disappear and the application's window to reappear. Even while the application is iconified, it does continue to run and perform whatever the user may have it doing.<br /> <br /> Some applications may also place an app icon on the Workbench background even while the application is open to allow the user to be able to drop other file icons on the app icon and have them be used by the application.<br /> <br /> === Graphic gadgets ===<br /> Within AmigaOS and application windows, there can be any number of graphic devices meant to be operated by your mouse with clicks and drags - these are known as &quot;gagdets&quot;. In most cases, the gagdets are simple analogs of real world objects - like buttons you press with your finger, forms you fill out with a pencil or tabs on folders.<br /> <br /> [[File:LibFig5-1.png]]<br /> <br /> ==== Buttons ====<br /> <br /> [[File:OS4-Buttons.jpg|frame|right]]<br /> Buttons (or &quot;Boolean gadgets&quot;) are some of the most common GUI objects. With a simple left-click of your mouse button, they are used to perform actions, set configurations or indicate choices. <br /> <br /> In AmigaOS, clicking &quot;down&quot; on a button typically causes the button to be rendered differently, to reflect that it has been &quot;pressed&quot;. Engaging the button is not actually recognized until you let go with the mouse button over the graphic gadget. This means that while the gadget has been clicked down, you always have the option of moving the mouse off the button gadget and then letting go and it will be as though the button had never been &quot;pressed&quot; or clicked on.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> ==== Text gadgets ====<br /> <br /> [[File:OS4-StringGadgets.jpg|frame|right]]<br /> A text gadget (or &quot;String gadget&quot;) works like a space in a paper form to be filled out - left click in the gadget, you will see a cursor appear and you can type your answer.<br /> Once you've finished typing your infrormation, you can either press the enter, carriage-return or tab keys for your entry to be recognized.<br /> <br /> Text or string gadgets can also come in a number of variants for specific uses. Some can limit input to be numeric only (and may have adjacent buttons to increment or decrement the value). Some string gadgets may be specifically be meant for file or directory names and they have adjacent gagdets that will bring up a file requester to set the value. Many times a numeric gadget is paired with a slider gadget (as in the example above), where the value can either be set by typing in the gadget or by using the slider.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> ==== Sliders &amp; Scroll Bars ====<br /> <br /> [[File:OS4-SliderGadgets.jpg|frame|right]]<br /> Slider gadgets work like controls many of have seen on their stereo systems - left-click and drag on the gadget &quot;knob&quot; to move it back and forth to set a value. A more sophisticated variant of the slider is the &quot;scroll bar&quot; that has a variably sized scroll bar contained in a scroll box that lets you see what proportion of the active range is visible or active.<br /> <br /> With all slider and scroller gadgets AmigaOS also lets you click in the area to either side of the knob or slider to adjust the setting. In the case of sliders, the value will typically move by a fixed amount (+/- 1 or some suitable increment). In the case of scroll bars, clicking in the scroll box on either side of the scroll bar will cause the value to move in increments of the scroll bar size. Scroll bars also come with &quot;scroll arrows&quot; at the end of the scroll box that allow for finer movement of the scroll bar.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> ==== Cycle gadgets ====<br /> <br /> [[File:OS4-CycleGadgets.jpg|frame|right]]<br /> Cycle gagdets are a variant on buttons that let you select from a number of specific choices. You can either click on the majority of the gadget to pop-up a list of choices to select from or click on the circular arrow to cycle between the list of choices. Cycle gagdets rarely cause actions to occur, they just adjust some setting or configuration.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> ==== Check Box &amp; Radio Button gadgets ====<br /> <br /> [[File:OS4-CheckRadioGadgets.jpg|frame|right]]<br /> Another variant of buttons, check boxes can be clicked to set on/off or yes/no conditions with a checkmark, just like a check box in a paper form. Radio buttons are another variant where two or more round buttons are presented in a set and only one of the set can be clicked and activated, like the buttons on a stereo system.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> ==== Tabs ====<br /> <br /> [[File:OS4-Tabs.jpg|frame|right]]<br /> Tabs are a graphical gadget that is used in combination with a &quot;pages&quot; or sets of gadgets and/or information, and you can click on the &quot;tabs&quot; to switch between the pages - like you might in a real notebook with tabbed pages. This provides a efficient way to present more information and settings in a compact interface.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> ====Requesters====<br /> <br /> [[File:LibFig2-5.png|frame|right]]<br /> As one uses AmigaOS and it's applications, from time to time a &quot;Requester&quot; window may appear to ask the user a question - basically windows with gadgets in them. Such requesters can appear to confirm an action, obtain more information, make a selection or configuration. Typically a series of buttons across the bottom of the window will dispatch the requester, with the bottom-left button gadget indicating some affirmative choice and the bottom-right button gagdet cancelling the requester (performing no action or change).<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> <br /> ====Keyboard Operation of Gadgets====<br /> As with so many things, AmigaOS and its applications provide a secondary way to operate many of these gadgets - by keyboard. If a window contains text gadgets, pressing your keyboard's TAB key will activate the text gadgets in sequence (a cursor will appear in each so you can type &amp; edit). Each press of the TAB key will cycle to the next gadget and pressing SHIFT + TAB will cycle through the gadgets in reverse order.<br /> <br /> You may have noticed in many of the above sample images that many of the gagdets or their adjacent &quot;label&quot; texts contain a single underlined character. This is a sign that pressing that key on your keyboard will activate that gadget. Each gadget can then be operated by your keyboard - just like clicking on a button, clicking on a tab, setting a text or numeric value, etc. Of course, if you are in the midst of typing in a text gadget, then things you type will go into that gadget instead of operating other gagdets.<br /> <br /> == Finding Files in AmigaOS ==<br /> <br /> [[File:OS4-ASLReq.jpg|frame|right]]<br /> AmigaOS provides a consistent method for navigating your file system and finding your files from within your apps - the &quot;ASL file requester&quot;. It is used by everything in AmigaOS and most third party applications. It is the window (or &quot;requester&quot;) that appears when you want to open or save files.<br /> <br /> As you can see, the ASL file requester presents the files in a given location in your file systems (a directory or &quot;drawer&quot;) and shows their size, date of creation or last modification and any comments attached to the file. The above example shows the same directory as appeared above in this page.<br /> <br /> At the bottom corners of the window are buttons to accept the selection (&quot;OK&quot;) or cancel the requester. Between those are buttons to view all the drives &amp; partitions on your system (&quot;Volumes&quot;) or to move to the &quot;Parent&quot; of the current directory.<br /> <br /> Also at the bottom of the window you will see three text gadgets. The first of these is optional and allows you to filter what is shown in the file list - it is now shown filtering out any file with a &quot;.info&quot; suffix (those are AmigaOS icon files). The next two lines reflect the current directory path name and the currently selected file name (also selected in the file list above). In the case of saving files, you would type any name you wanted in the bottom text field to create a new file. Clicking on the titles of the file list will let you sort the file list.<br /> <br /> Of course this being AmigaOS, the ASL requester has its own &quot;preferences editor&quot; that lets you set how the requester appears, is sorted by default and a number of mouse button short-cuts.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> <br /> == Controlling AmigaOS - Which Way? ==<br /> <br /> AmigaOS provides a number of parallel ways that the user can control and put their Amigas to use. The easiest and most common method is to use the AmigaOS graphic icons, windows and mouse interface - the &quot;Workbench&quot; - using all the GUI elements described above. But AmigaOS also provides a more traditional or &quot;old fashioned&quot; method called a command line interface (the &quot;CLI&quot; or &quot;Shell&quot;), where the user can type text commands and interact using a text interface. AmigaOS also provides a unique means of &quot;interprocess communications&quot; where user can have many applications and parts of the OS &quot;talk&quot; to each other. <br /> <br /> === The Workbench &amp; Intuition ===<br /> <br /> As we described above, AmigaOS provides the &quot;Workbench&quot;, a straightforward, efficient and easy graphical means to start applications, manage your computer and all your files. Files and programs are represented with icons, generally known as &quot;Projects&quot; and &quot;Tools&quot;. They can be stored in any arrangement of directories (&quot;Drawers&quot;). You double-click on a program icon and it will open in a Intuition GUI window on your Workbench screen. <br /> <br /> Please see the section about the AmigaOS [http://wiki.amigaos.net/index.php/UserDoc:Workbench Workbench] to learn these concepts:<br /> <br /> * What is the Workbench<br /> * Workbench menus<br /> * Keyboard control<br /> * Workbench requesters<br /> * Configuration<br /> * Workbench help<br /> <br /> === The Shell &amp; DOS Commands ===<br /> <br /> [[File:OS4-Window-Shell.jpg|frame|right]]<br /> The AmigaOS Shell can be opened by double-clicking the &quot;Shell&quot; icon in the AmigaOS &quot;System&quot; drawer. The Shell is a text based interface that allows you to perform most of the same operations as the Workbench - to run and interact with application programs, manage files and control your Amiga computer. AmigaOS also comes with dozens of standard &quot;DOS commands&quot; (programs purely meant for Shell usage). Simply enter the name of a program or command (like &quot;dir&quot;) and press Enter, the command or program will run and it will print its results in the Shell window. While considered old fashioned, many users find the Shell to still be the most efficient way to perform many tasks on the Amigas.<br /> <br /> Please see the section on the [[UserDoc:Shell|AmigaOS Shell]] to learn more.<br /> &lt;br style=&quot;clear: both&quot; /&gt;<br /> <br /> === Scripts &amp; Messages ===<br /> <br /> Scripts are simple text files that contain a list of commands written in a variety of languages: the AmigaDOS, Arexx and Python languages are provided with AmigaOS - there are many others. Each of these language has its strengths. You'll have to learn the one that suits what you want to do. You can create a script using a text editor. You can run such script from the Workbench or from the shell (or from any other script). By using ARexx ports provided by AmigaOS components (the Workbench or Multiview, for example) or third-party applications, scripts can be used to make your computer perform a wide variety of actions.<br /> <br /> == AmigaOS System Tools ==<br /> AmigaOS comes with a variety of programs to help in the preparation of your computer. These include tools for:<br /> <br /> * Drive preparation (Media Toolbox, Format, Format DCRW &amp; Mounter).<br /> * Font Handling (TypeManager &amp; FixFonts).<br /> * Script Languages (RexxMast and Python).<br /> * The Shell.<br /> * Miscellaneous Utilities (Find, Help, Grim Reaper &amp; Ringhio Server).<br /> <br /> == AmigaOS Utilities ==<br /> AmigaOS comes with a selection of utilities to assist the user, including:<br /> <br /> * Commodities.<br /> * Editors (Notepad, MEmacs, PrefsObjectEditor &amp; IconEdit).<br /> * Postscript oriented apps (AmiPDF, AmiGS &amp; Ghostscript).<br /> * Disk apps (PartitionWizard &amp; RawDisk).<br /> * Screenblankers.<br /> * AmiDock and Dockies.<br /> * The Unarc dearchiver.<br /> * PlayCD.<br /> * Miscellaneous apps (Clock, printing apps, KeyShow, install apps, etc.).</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=Installation_Utility&diff=6286 Installation Utility 2013-08-03T21:08:13Z <p>Philippe Ferrucci: /* SetString, SetInteger, SetObject */</p> <hr /> <div>= How the installer works =<br /> <br /> == Basic concept ==<br /> <br /> The installation utility executes a python script that sets up the installation. In addition to standard Python commands the installation utility provides a module called &quot;installer&quot; and an interface to it. Using this interface you can create the different pages that can be found in almost all installation processes: a welcome page, a displayed licence page, a selection page, an installation page and finally a finish page.<br /> In the end, there are only a few script commands required.<br /> <br /> == Running an installation script ==<br /> <br /> === From the command line ===<br /> <br /> In order to run an installation from the command line, invoke the installation utility giving your script file as an argument and if you want a logo to be displayed at the top of the window:<br /> <br /> &lt;pre&gt;<br /> &quot;SYS:Utilities/Installation utility&quot; PACKAGE=myscript.py LOGO=mylogo.png<br /> &lt;/pre&gt;<br /> Note: the logo will be displayed all along the installation process.<br /> <br /> ''Note2: right now you need to set these argument names with capital letters, as shown above.''<br /> <br /> === From the Workbench ===<br /> <br /> Add a project icon to your script and use ''SYS:Utilities/Installation utility'' as the default tool.<br /> <br /> ==== Tooltypes ====<br /> <br /> * PACKAGE (Default: ''package.py'')<br /> <br /> This tooltype is used to specify the script name to execute. It is useful if you want to use a standalone icon that will open a script with a different name or in another directory.<br /> <br /> * LOGO<br /> <br /> You can use this tooltype to specify an image name to use in the installer window.<br /> <br /> = Example script =<br /> <br /> A minimal install script looks like this:<br /> <br /> &lt;pre&gt;<br /> # Simple, basic installation script<br /> from installer import *<br /> <br /> # These will be used for the first page (welcome) and last page (finish)<br /> welcomeText = &quot;This is a welcome text, displayed at the first page&quot;<br /> finishText = &quot;This is the finish message&quot;<br /> <br /> # Define the Welcome page<br /> welcomePage = NewPage(WELCOME)<br /> SetString(welcomePage, &quot;message&quot;, welcomeText)<br /> <br /> # Define the License page. The user must accept this license to continue the install process.<br /> # The license text will be read from a text file called &quot;license.txt&quot; and will be displayed on the page.<br /> licensePage = NewPage(LICENSE)<br /> <br /> # Define a page to select the installation directory<br /> destinationPage = NewPage(DESTINATION)<br /> SetString(destinationPage, &quot;message&quot;, &quot;Please indicate where you want to install the files .&quot;)<br /> SetString(destinationPage, &quot;destination&quot;, &quot;SYS:&quot;)<br /> <br /> # Define a directory to be copied to the destination<br /> filePack = AddPackage (FILEPACKAGE,<br /> name = &quot;Full directory&quot;,<br /> description = &quot;Directory to copy as-is in the destination&quot;,<br /> files = [&quot;data&quot;],<br /> optional = False<br /> )<br /> <br /> # Define a progress page that is shown during the installation<br /> installPage = NewPage(INSTALL)<br /> <br /> # Create a &quot;finish&quot; page.<br /> finalPage = NewPage(FINISH)<br /> SetString(finalPage, &quot;message&quot;, finishText)<br /> <br /> # Finally, this runs the installation.<br /> RunInstaller()<br /> &lt;/pre&gt;<br /> <br /> = Python Interface =<br /> <br /> == Introduction ==<br /> <br /> The installer is entirely programmed in Python. For this purpose, it provides a Python module called 'installer' that serves as a functional interface to the GUI. The entire GUI is build out of pages. Pages present different kind of information to the user. The installation can be navigated with a pair of forward/backward buttons to visit each page in turn. Certain pages (notably the INSTALL page) will trigger the installation process itself, although the interface is flexible enough to make an installation that is entirely driven by the Python script. A minimal setup function will create a &quot;default&quot; layout of pages for an installer. The basic is to have a single archive that is installed into a destination drawer created on the disk - about 90% of all installers will do exactly this. Therefore a lot of the mechanics involved in this type of installer is automated.<br /> <br /> == Python Functions in the installer package ==<br /> <br /> === NewPage ===<br /> <br /> This function creates a new page and returns its page number for later reference. The only argument to the function is the type of page to create. Possible values are:<br /> <br /> ; WELCOME<br /> : A message page, usually used for displaying a &quot;welcome&quot; message, although other uses are perfectly possible as well.<br /> : ''Note:'' this page is mandatory.<br /> <br /> ; FINISH<br /> : A message page that is specifically targeted at closing the installation. This page automatically gets the &quot;finish&quot; attribute set to make the installation change the &quot;cancel&quot; to the &quot;finish&quot; button.<br /> <br /> ; DESTINATION<br /> : A page to select a directory to serve as the target for the installation.<br /> : ''Note:'' this page is mandatory.<br /> <br /> ; INSTALL<br /> : The presence of this page automatically triggers the installation of the selected packages.<br /> <br /> ; GUI<br /> : A page where GUI elements can be added and controlled via a Python handler.<br /> <br /> ; PROCESSING<br /> : A page to display a simple progress bar for doing some Python-scripted processing.<br /> <br /> ; LICENSE<br /> : A brickwall page that displays a license agreement that only lets the user continue after accepting the license.<br /> : ''Note:'' the installation utility will look for a text file called &quot;license_''languagename''.language.txt&quot;, if not found, it will look for a file called &quot;license.txt&quot;.<br /> <br /> ; README<br /> : A page that displays a text file from disk for reference/README purposes.<br /> <br /> If the page cannot be generated, an OSError exception is raised.<br /> <br /> === GotoPage ===<br /> <br /> This function accepts a single argument, the page to display. This function should rarely be needed.<br /> <br /> === SetString, SetInteger, SetObject ===<br /> <br /> This function sets a variable of the specified type on a page. It accepts three parameters:<br /> * The Page number to set the variable on<br /> * The name of the variable<br /> * The variable content.<br /> <br /> === GetString, GetInteger, GetObject ===<br /> <br /> These functions are the reverse of the above - they read a variable from the page specified as its first argument and the name specified as the second argument. They return a default value if the name was not found.<br /> <br /> === RunInstaller ===<br /> <br /> This function runs the installer's main loop, and needs to be the last command in an installation. Any subsequent scripting is done via handlers connected to the pages.<br /> <br /> === AddPackage ===<br /> <br /> This function adds a package to the list of installable packages. The function's interface uses keywords to make it more readable. The keywords are<br /> <br /> ; type<br /> : The type of package. This can be either FILEPACKAGE, ARCHIVEPACKAGE or HANDLERPACKAGE. A file package copies a list of files to the destination. An archive package unpacks a list of archives at the destination. Finally, a handler package is an abstract package that executes a handler when it is installed or upon certain actions.<br /> : This argument MUST be given.<br /> <br /> ; name<br /> : A string that specifies the name of the package. This name is presented to the user of the installer on a PACKAGESELECT page.<br /> : A name should be given. It defaults to an empty string.<br /> <br /> ; description<br /> : A textual description of the package. It is presented to the user next to the package list on a PACKAGESELECT page if the package is selected in the package list.<br /> : The description may be empty, although it is consider bad style. It defaults to an empty string.<br /> <br /> ; optional<br /> : A boolean value indicating whether the package is optional to install or required to be installed. A value of True means the package is optional.<br /> : Default is True (package is optional)<br /> <br /> ; selected<br /> : A boolean indicating whether the package should be pre-selected or not. If True, the package is selected the first time the PACKAGESELECT page is entered.<br /> : Default is True (package is selected), although the user might deselect the package on a PACKAGESELECT page<br /> <br /> ; diskspace<br /> : An integer value specifying the number of bytes the package occupies after installation. If a zero size is given (or the parameter is omitted) the installer tries to figure out the size requirements automatically, but be warned this might be a time consuming process.<br /> : Defaults to zero (try to figure out yourself)<br /> <br /> ; featuregroup<br /> : An integer bitmask giving one bit of each feature group defined. A one bit indicates this package is part of the group, while a zero bit indicates it isn't.<br /> : Defaults to zero (not in any feature group)<br /> <br /> ; alternatepath<br /> : Specifies an alternative installation path. For example, some files might need to be installed into LIBS: instead of the usual destination. This feature should be used with care.<br /> : Defaults to None (i.e. no alternate path)<br /> <br /> ; files<br /> : A list of strings, each string representing one file associated with this package. The interpretation of these files depend on the package type:<br /> :: ARCHIVEPACKAGE: each file is an archive that is supposed to be extracted into the destination.<br /> :: HANDLERPACKAGE: The strings are not interpreted in any way, it is up to the handler to do that.<br /> :: FILEPACKAGE: Each string stands for a file or directory to be copied. Files are straight copies, while directory names are interpreted slightly different: if a directory name is given, that entire directory is copied to the destination, including the directory itself. For example, if you specify &quot;System&quot; then the destination directory will include a &quot;System&quot; directory. On the other hand, if you specify it as &quot;System/&quot; with a trailing slash, the content of the directory will be copied but not the directory itself, i.e. the destination directory would contain all the file and directories in the &quot;System&quot; directory but not the directory itself.<br /> :: ''Note:'' directory/file names must be relative to the current directory i.e. where the installer is executed. You cannot use here a complete path name with the volume name like ''RAM:mydir''.<br /> : The default is an empty list.<br /> <br /> The result of this function is a package number, which can be used subsequently to adjust package settings or query certain features.<br /> <br /> == GUI's ==<br /> <br /> GUI's must be created from scratch using a procedural interface. The following procedures deal with creating and handling the user interface. In general, the user interface must be generated once and cannot be changed afterwards (with exceptions, see below).<br /> <br /> A GUI is started with a call to StartGUI(page_number). This will start to create a GUI on the indicated page number, and all subsequent calls will add to this GUI until EndGUI() is called. If the indicated page number is invalid or is not a GUI page, ever subsequent calls are ignored until a new StartGUI with a valid page number is called.<br /> <br /> Immediately after the call, a single GUI object might be defined. In almost all cases, this will be a group to hold a number of GUI elements. Groups are defined with the BeginGroup and EndGroup calls.<br /> <br /> BeginGroup takes the following keyword arguments:<br /> ; orientation<br /> : This specifies whether the children of this group are laid out vertically or horizontally. By default the layout is vertically.<br /> ; label<br /> : A short text string that can be displayed as a label for this group. The label is only used if a frame other than NONE_FRAME is specified. By default no label is used.<br /> ; frame<br /> : One of the constants NONE_FRAME, THIN_FRAME, BUTTON_FRAME, GROUP_FRAME, FIELD_FRAME, DROPBOX_FRAME, SBAR_HORIZ_FRAME, SBAR_VERT_FRAME, BOX_FRAME, STANDARD_FRAME. They directly correspond to the bevel styles of bevel.image. Defaults to NONE_FRAME.<br /> ; weight<br /> : An integer defining the weighted width or height of this group. This corresponds to layout.gadget's CHILD_WeightedWidth or CHILD_WeightedHeight tags, depending on the layout direction.<br /> <br /> EndGroup has no parameters and automatically terminates the last group opened by BeginGroup.<br /> <br /> User interface elements are added with the following calls. All of these return an ID number.<br /> <br /> === AddLabel ===<br /> <br /> This call adds a text label, with selectable frame. The following keyword arguments are supported:<br /> ; label<br /> : A string that specifies the label to be displayed. Default is empty, although an empty label doesn't make much sense<br /> <br /> ; weight<br /> : The weight of the label, as explained above.<br /> <br /> ; frame<br /> : A frame to put around the label.<br /> <br /> === AddButton ===<br /> <br /> This call adds a push button object to the current group. The function supports the following keyword arguments:<br /> ; label<br /> : A string specifying the label to be displayed within the button. Defaults to an empty label.<br /> <br /> ; frame<br /> : One of the constants mentioned above for the group. Defaults to BUTTON_FRAME.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; onclick<br /> : A Python callable object that is invoked when the button is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id) where page_number is the page number of the GUI page and element_id is the element id returned by this call.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddCheckBox ===<br /> <br /> This call adds a checkbox object to the GUI. The following keyword arguments are valid:<br /> <br /> ; label<br /> : A string that appears as a label to the right of the checkbox. Defaults to an empty label.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; checked<br /> : An integer that specifies whether the checkbox is initially checked or not. A zero means the checkbox is clear, any other value says the box is checked.<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the checkbox is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, state) where page_number and element_id are the same as above, and state is a 0 if the user just unchecked the checkbox, or a 1 is it was just checked.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddRadioButton ===<br /> <br /> This call adds a set of mutually exclusive radio buttons. The following keyword arguments are valid:<br /> <br /> ; labels<br /> : A list of Python strings, with each of these strings appearing as a choice on the Radio buttons. This parameter is required.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; selected<br /> : The number of the button initially selected. Defaults to the first button (0).<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the radio button is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the button number that was selected.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddChooser ===<br /> <br /> This function adds a chooser gadget to the GUI. The following keyword arguments are valid:<br /> <br /> ; label<br /> : A test string to be displayed in the chooser in pop-up mode (see below). Defaults to an empty string, and is not used for drop-down mode.<br /> <br /> ; choices<br /> : A list of text strings to be displayed as choices for the chooser. This argument is mandatory.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; selected<br /> : The number of the currently visible item in drop-down mode. Defaults to 0.<br /> <br /> ; mode: One of the constants CHOOSER_POPUP or CHOOSER_DROPDOWN. This corresponds to the chooser.gadget CHOOSER_PopUp and CHOOSER_DropDown tag items.<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the chooser is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the title number that was selected.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddSpace ===<br /> <br /> This call adds a bit of space to the GUI. It accepts only one parameter:<br /> <br /> ; weight<br /> : An integer specifying the weight of the space. Defaults to 1.<br /> <br /> The call does not return a value. Space does not have any variables.<br /> <br /> == User Interface Settings ==<br /> <br /> In order to change some aspects of user interface elements (like the selection status of a checkbox) or read their current state, two functions exist called GetUIAttr and SetUIAttr.<br /> <br /> The former reads an attribute from an identified user interface element (identified by the page number and element id) while the latter sets (and updates the on-screen representation) of an equally identified element.<br /> <br /> A number of attributes can be set and gotten from UI elements; some of them are shared among more than one element type, while others are specific. The following list names the attributes:<br /> <br /> ; GUI_LABEL (string)<br /> : The label displayed on a UI element.<br /> : Applies to BUTTON, LABEL, GROUP, CHECKBOX<br /> <br /> ; GUI_SELECTED (integer)<br /> : The selected item in a chooser or radio button.<br /> : Applies to CHOOSER and RADIOBUTTON<br /> <br /> ; GUI_CHECKED (integer)<br /> : Whether the checkbox checkmark is set or not.<br /> : Applies to CHECKBOX<br /> <br /> ; GUI_ONCLICK (Python callable)<br /> : The handler invoked when the UI element is activated.<br /> : Applies to CHOOSER, BUTTON, LABEL, GROUP, CHECKBOX, RADIOBUTTON<br /> <br /> The GetUIAttr function's prototype looks like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> result = GetUIAttr(page_nr, id, attr)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> page_nr and id identify the object by giving the GUI's page number and the element id returned by the creation call. The attr parameter is one of the attributes given above. Valid parameters for attr are GUI_SELECTED, GUI_CHECKED and GUI_ONCLICK.<br /> <br /> For SetUIAttr, the prototype looks like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> SetUIAttr(page_nr, id, attr, value)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> page_nr and id and attr are the same as above. The value parameter specifies the new value of the attribute, and must match the type for the attribute or the call will have no effect.<br /> <br /> = Hints =<br /> <br /> * See the AmigaOS 4 installation script on the AmigaOS Installation CD. It is a big script full of functions. Take it as example and experiment.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=Installation_Utility&diff=6285 Installation Utility 2013-08-03T20:39:12Z <p>Philippe Ferrucci: </p> <hr /> <div>= How the installer works =<br /> <br /> == Basic concept ==<br /> <br /> The installation utility executes a python script that sets up the installation. In addition to standard Python commands the installation utility provides a module called &quot;installer&quot; and an interface to it. Using this interface you can create the different pages that can be found in almost all installation processes: a welcome page, a displayed licence page, a selection page, an installation page and finally a finish page.<br /> In the end, there are only a few script commands required.<br /> <br /> == Running an installation script ==<br /> <br /> === From the command line ===<br /> <br /> In order to run an installation from the command line, invoke the installation utility giving your script file as an argument and if you want a logo to be displayed at the top of the window:<br /> <br /> &lt;pre&gt;<br /> &quot;SYS:Utilities/Installation utility&quot; PACKAGE=myscript.py LOGO=mylogo.png<br /> &lt;/pre&gt;<br /> Note: the logo will be displayed all along the installation process.<br /> <br /> ''Note2: right now you need to set these argument names with capital letters, as shown above.''<br /> <br /> === From the Workbench ===<br /> <br /> Add a project icon to your script and use ''SYS:Utilities/Installation utility'' as the default tool.<br /> <br /> ==== Tooltypes ====<br /> <br /> * PACKAGE (Default: ''package.py'')<br /> <br /> This tooltype is used to specify the script name to execute. It is useful if you want to use a standalone icon that will open a script with a different name or in another directory.<br /> <br /> * LOGO<br /> <br /> You can use this tooltype to specify an image name to use in the installer window.<br /> <br /> = Example script =<br /> <br /> A minimal install script looks like this:<br /> <br /> &lt;pre&gt;<br /> # Simple, basic installation script<br /> from installer import *<br /> <br /> # These will be used for the first page (welcome) and last page (finish)<br /> welcomeText = &quot;This is a welcome text, displayed at the first page&quot;<br /> finishText = &quot;This is the finish message&quot;<br /> <br /> # Define the Welcome page<br /> welcomePage = NewPage(WELCOME)<br /> SetString(welcomePage, &quot;message&quot;, welcomeText)<br /> <br /> # Define the License page. The user must accept this license to continue the install process.<br /> # The license text will be read from a text file called &quot;license.txt&quot; and will be displayed on the page.<br /> licensePage = NewPage(LICENSE)<br /> <br /> # Define a page to select the installation directory<br /> destinationPage = NewPage(DESTINATION)<br /> SetString(destinationPage, &quot;message&quot;, &quot;Please indicate where you want to install the files .&quot;)<br /> SetString(destinationPage, &quot;destination&quot;, &quot;SYS:&quot;)<br /> <br /> # Define a directory to be copied to the destination<br /> filePack = AddPackage (FILEPACKAGE,<br /> name = &quot;Full directory&quot;,<br /> description = &quot;Directory to copy as-is in the destination&quot;,<br /> files = [&quot;data&quot;],<br /> optional = False<br /> )<br /> <br /> # Define a progress page that is shown during the installation<br /> installPage = NewPage(INSTALL)<br /> <br /> # Create a &quot;finish&quot; page.<br /> finalPage = NewPage(FINISH)<br /> SetString(finalPage, &quot;message&quot;, finishText)<br /> <br /> # Finally, this runs the installation.<br /> RunInstaller()<br /> &lt;/pre&gt;<br /> <br /> = Python Interface =<br /> <br /> == Introduction ==<br /> <br /> The installer is entirely programmed in Python. For this purpose, it provides a Python module called 'installer' that serves as a functional interface to the GUI. The entire GUI is build out of pages. Pages present different kind of information to the user. The installation can be navigated with a pair of forward/backward buttons to visit each page in turn. Certain pages (notably the INSTALL page) will trigger the installation process itself, although the interface is flexible enough to make an installation that is entirely driven by the Python script. A minimal setup function will create a &quot;default&quot; layout of pages for an installer. The basic is to have a single archive that is installed into a destination drawer created on the disk - about 90% of all installers will do exactly this. Therefore a lot of the mechanics involved in this type of installer is automated.<br /> <br /> == Python Functions in the installer package ==<br /> <br /> === NewPage ===<br /> <br /> This function creates a new page and returns its page number for later reference. The only argument to the function is the type of page to create. Possible values are:<br /> <br /> ; WELCOME<br /> : A message page, usually used for displaying a &quot;welcome&quot; message, although other uses are perfectly possible as well.<br /> : ''Note:'' this page is mandatory.<br /> <br /> ; FINISH<br /> : A message page that is specifically targeted at closing the installation. This page automatically gets the &quot;finish&quot; attribute set to make the installation change the &quot;cancel&quot; to the &quot;finish&quot; button.<br /> <br /> ; DESTINATION<br /> : A page to select a directory to serve as the target for the installation.<br /> : ''Note:'' this page is mandatory.<br /> <br /> ; INSTALL<br /> : The presence of this page automatically triggers the installation of the selected packages.<br /> <br /> ; GUI<br /> : A page where GUI elements can be added and controlled via a Python handler.<br /> <br /> ; PROCESSING<br /> : A page to display a simple progress bar for doing some Python-scripted processing.<br /> <br /> ; LICENSE<br /> : A brickwall page that displays a license agreement that only lets the user continue after accepting the license.<br /> : ''Note:'' the installation utility will look for a text file called &quot;license_''languagename''.language.txt&quot;, if not found, it will look for a file called &quot;license.txt&quot;.<br /> <br /> ; README<br /> : A page that displays a text file from disk for reference/README purposes.<br /> <br /> If the page cannot be generated, an OSError exception is raised.<br /> <br /> === GotoPage ===<br /> <br /> This function accepts a single argument, the page to display. This function should rarely be needed.<br /> <br /> === SetString, SetInteger, SetObject ===<br /> <br /> This function sets a variable of the specified type on a page. It accepts three parameters:<br /> * # The Page number to set the variable on<br /> * # The name of the variable<br /> * # The variable content.<br /> <br /> === GetString, GetInteger, GetObject ===<br /> <br /> These functions are the reverse of the above - they read a variable from the page specified as its first argument and the name specified as the second argument. They return a default value if the name was not found.<br /> <br /> === RunInstaller ===<br /> <br /> This function runs the installer's main loop, and needs to be the last command in an installation. Any subsequent scripting is done via handlers connected to the pages.<br /> <br /> === AddPackage ===<br /> <br /> This function adds a package to the list of installable packages. The function's interface uses keywords to make it more readable. The keywords are<br /> <br /> ; type<br /> : The type of package. This can be either FILEPACKAGE, ARCHIVEPACKAGE or HANDLERPACKAGE. A file package copies a list of files to the destination. An archive package unpacks a list of archives at the destination. Finally, a handler package is an abstract package that executes a handler when it is installed or upon certain actions.<br /> : This argument MUST be given.<br /> <br /> ; name<br /> : A string that specifies the name of the package. This name is presented to the user of the installer on a PACKAGESELECT page.<br /> : A name should be given. It defaults to an empty string.<br /> <br /> ; description<br /> : A textual description of the package. It is presented to the user next to the package list on a PACKAGESELECT page if the package is selected in the package list.<br /> : The description may be empty, although it is consider bad style. It defaults to an empty string.<br /> <br /> ; optional<br /> : A boolean value indicating whether the package is optional to install or required to be installed. A value of True means the package is optional.<br /> : Default is True (package is optional)<br /> <br /> ; selected<br /> : A boolean indicating whether the package should be pre-selected or not. If True, the package is selected the first time the PACKAGESELECT page is entered.<br /> : Default is True (package is selected), although the user might deselect the package on a PACKAGESELECT page<br /> <br /> ; diskspace<br /> : An integer value specifying the number of bytes the package occupies after installation. If a zero size is given (or the parameter is omitted) the installer tries to figure out the size requirements automatically, but be warned this might be a time consuming process.<br /> : Defaults to zero (try to figure out yourself)<br /> <br /> ; featuregroup<br /> : An integer bitmask giving one bit of each feature group defined. A one bit indicates this package is part of the group, while a zero bit indicates it isn't.<br /> : Defaults to zero (not in any feature group)<br /> <br /> ; alternatepath<br /> : Specifies an alternative installation path. For example, some files might need to be installed into LIBS: instead of the usual destination. This feature should be used with care.<br /> : Defaults to None (i.e. no alternate path)<br /> <br /> ; files<br /> : A list of strings, each string representing one file associated with this package. The interpretation of these files depend on the package type:<br /> :: ARCHIVEPACKAGE: each file is an archive that is supposed to be extracted into the destination.<br /> :: HANDLERPACKAGE: The strings are not interpreted in any way, it is up to the handler to do that.<br /> :: FILEPACKAGE: Each string stands for a file or directory to be copied. Files are straight copies, while directory names are interpreted slightly different: if a directory name is given, that entire directory is copied to the destination, including the directory itself. For example, if you specify &quot;System&quot; then the destination directory will include a &quot;System&quot; directory. On the other hand, if you specify it as &quot;System/&quot; with a trailing slash, the content of the directory will be copied but not the directory itself, i.e. the destination directory would contain all the file and directories in the &quot;System&quot; directory but not the directory itself.<br /> :: ''Note:'' directory/file names must be relative to the current directory i.e. where the installer is executed. You cannot use here a complete path name with the volume name like ''RAM:mydir''.<br /> : The default is an empty list.<br /> <br /> The result of this function is a package number, which can be used subsequently to adjust package settings or query certain features.<br /> <br /> == GUI's ==<br /> <br /> GUI's must be created from scratch using a procedural interface. The following procedures deal with creating and handling the user interface. In general, the user interface must be generated once and cannot be changed afterwards (with exceptions, see below).<br /> <br /> A GUI is started with a call to StartGUI(page_number). This will start to create a GUI on the indicated page number, and all subsequent calls will add to this GUI until EndGUI() is called. If the indicated page number is invalid or is not a GUI page, ever subsequent calls are ignored until a new StartGUI with a valid page number is called.<br /> <br /> Immediately after the call, a single GUI object might be defined. In almost all cases, this will be a group to hold a number of GUI elements. Groups are defined with the BeginGroup and EndGroup calls.<br /> <br /> BeginGroup takes the following keyword arguments:<br /> ; orientation<br /> : This specifies whether the children of this group are laid out vertically or horizontally. By default the layout is vertically.<br /> ; label<br /> : A short text string that can be displayed as a label for this group. The label is only used if a frame other than NONE_FRAME is specified. By default no label is used.<br /> ; frame<br /> : One of the constants NONE_FRAME, THIN_FRAME, BUTTON_FRAME, GROUP_FRAME, FIELD_FRAME, DROPBOX_FRAME, SBAR_HORIZ_FRAME, SBAR_VERT_FRAME, BOX_FRAME, STANDARD_FRAME. They directly correspond to the bevel styles of bevel.image. Defaults to NONE_FRAME.<br /> ; weight<br /> : An integer defining the weighted width or height of this group. This corresponds to layout.gadget's CHILD_WeightedWidth or CHILD_WeightedHeight tags, depending on the layout direction.<br /> <br /> EndGroup has no parameters and automatically terminates the last group opened by BeginGroup.<br /> <br /> User interface elements are added with the following calls. All of these return an ID number.<br /> <br /> === AddLabel ===<br /> <br /> This call adds a text label, with selectable frame. The following keyword arguments are supported:<br /> ; label<br /> : A string that specifies the label to be displayed. Default is empty, although an empty label doesn't make much sense<br /> <br /> ; weight<br /> : The weight of the label, as explained above.<br /> <br /> ; frame<br /> : A frame to put around the label.<br /> <br /> === AddButton ===<br /> <br /> This call adds a push button object to the current group. The function supports the following keyword arguments:<br /> ; label<br /> : A string specifying the label to be displayed within the button. Defaults to an empty label.<br /> <br /> ; frame<br /> : One of the constants mentioned above for the group. Defaults to BUTTON_FRAME.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; onclick<br /> : A Python callable object that is invoked when the button is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id) where page_number is the page number of the GUI page and element_id is the element id returned by this call.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddCheckBox ===<br /> <br /> This call adds a checkbox object to the GUI. The following keyword arguments are valid:<br /> <br /> ; label<br /> : A string that appears as a label to the right of the checkbox. Defaults to an empty label.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; checked<br /> : An integer that specifies whether the checkbox is initially checked or not. A zero means the checkbox is clear, any other value says the box is checked.<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the checkbox is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, state) where page_number and element_id are the same as above, and state is a 0 if the user just unchecked the checkbox, or a 1 is it was just checked.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddRadioButton ===<br /> <br /> This call adds a set of mutually exclusive radio buttons. The following keyword arguments are valid:<br /> <br /> ; labels<br /> : A list of Python strings, with each of these strings appearing as a choice on the Radio buttons. This parameter is required.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; selected<br /> : The number of the button initially selected. Defaults to the first button (0).<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the radio button is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the button number that was selected.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddChooser ===<br /> <br /> This function adds a chooser gadget to the GUI. The following keyword arguments are valid:<br /> <br /> ; label<br /> : A test string to be displayed in the chooser in pop-up mode (see below). Defaults to an empty string, and is not used for drop-down mode.<br /> <br /> ; choices<br /> : A list of text strings to be displayed as choices for the chooser. This argument is mandatory.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; selected<br /> : The number of the currently visible item in drop-down mode. Defaults to 0.<br /> <br /> ; mode: One of the constants CHOOSER_POPUP or CHOOSER_DROPDOWN. This corresponds to the chooser.gadget CHOOSER_PopUp and CHOOSER_DropDown tag items.<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the chooser is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the title number that was selected.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddSpace ===<br /> <br /> This call adds a bit of space to the GUI. It accepts only one parameter:<br /> <br /> ; weight<br /> : An integer specifying the weight of the space. Defaults to 1.<br /> <br /> The call does not return a value. Space does not have any variables.<br /> <br /> == User Interface Settings ==<br /> <br /> In order to change some aspects of user interface elements (like the selection status of a checkbox) or read their current state, two functions exist called GetUIAttr and SetUIAttr.<br /> <br /> The former reads an attribute from an identified user interface element (identified by the page number and element id) while the latter sets (and updates the on-screen representation) of an equally identified element.<br /> <br /> A number of attributes can be set and gotten from UI elements; some of them are shared among more than one element type, while others are specific. The following list names the attributes:<br /> <br /> ; GUI_LABEL (string)<br /> : The label displayed on a UI element.<br /> : Applies to BUTTON, LABEL, GROUP, CHECKBOX<br /> <br /> ; GUI_SELECTED (integer)<br /> : The selected item in a chooser or radio button.<br /> : Applies to CHOOSER and RADIOBUTTON<br /> <br /> ; GUI_CHECKED (integer)<br /> : Whether the checkbox checkmark is set or not.<br /> : Applies to CHECKBOX<br /> <br /> ; GUI_ONCLICK (Python callable)<br /> : The handler invoked when the UI element is activated.<br /> : Applies to CHOOSER, BUTTON, LABEL, GROUP, CHECKBOX, RADIOBUTTON<br /> <br /> The GetUIAttr function's prototype looks like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> result = GetUIAttr(page_nr, id, attr)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> page_nr and id identify the object by giving the GUI's page number and the element id returned by the creation call. The attr parameter is one of the attributes given above. Valid parameters for attr are GUI_SELECTED, GUI_CHECKED and GUI_ONCLICK.<br /> <br /> For SetUIAttr, the prototype looks like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> SetUIAttr(page_nr, id, attr, value)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> page_nr and id and attr are the same as above. The value parameter specifies the new value of the attribute, and must match the type for the attribute or the call will have no effect.<br /> <br /> = Hints =<br /> <br /> * See the AmigaOS 4 installation script on the AmigaOS Installation CD. It is a big script full of functions. Take it as example and experiment.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=Installation_Utility&diff=6284 Installation Utility 2013-08-03T19:31:48Z <p>Philippe Ferrucci: /* Example script */</p> <hr /> <div>= How the installer works =<br /> <br /> == Basic concept ==<br /> <br /> The installation utility executes a python script that sets up the installation. In addition to standard Python commands the installation utility provides a module called &quot;installer&quot; and an interface to it. Using this interface you can create the different pages that can be found in almost all installation processes: a welcome page, a displayed licence page, a selection page, an installation page and finally a finish page.<br /> In the end, there are only a few script commands required.<br /> <br /> == Running an installation script ==<br /> <br /> === From the command line ===<br /> <br /> In order to run an installation from the command line, invoke the installation utility giving your script file as an argument and if you want a logo to be displayed at the top of the window:<br /> <br /> &lt;pre&gt;<br /> &quot;SYS:Utilities/Installation utility&quot; PACKAGE=myscript.py LOGO=mylogo.png<br /> &lt;/pre&gt;<br /> Note: the logo will be displayed all along the installation process.<br /> <br /> ''Note2: right now you need to set these argument names with capital letters, as shown above.''<br /> <br /> === From the Workbench ===<br /> <br /> Add a project icon to your script and use ''SYS:Utilities/Installation utility'' as the default tool.<br /> <br /> ==== Tooltypes ====<br /> <br /> * PACKAGE (Default: ''package.py'')<br /> <br /> This tooltype is used to specify the script name to execute. It is useful if you want to use a standalone icon that will open a script with a different name or in another directory.<br /> <br /> * LOGO<br /> <br /> You can use this tooltype to specify an image name to use in the installer window.<br /> <br /> = Example script =<br /> <br /> A minimal install script looks like this:<br /> <br /> &lt;pre&gt;<br /> # Simple, basic installation script<br /> from installer import *<br /> <br /> # These will be used for the first page (welcome) and last page (finish)<br /> welcomeText = &quot;This is a welcome text, displayed at the first page&quot;<br /> finishText = &quot;This is the finish message&quot;<br /> <br /> # Define the Welcome page<br /> welcomePage = NewPage(WELCOME)<br /> SetString(welcomePage, &quot;message&quot;, welcomeText)<br /> <br /> # Define the License page. The user must accept this license to continue the install process.<br /> # The license text will be read from a text file called &quot;license.txt&quot; and will be displayed on the page.<br /> licensePage = NewPage(LICENSE)<br /> <br /> # Define a page to select the installation directory<br /> destinationPage = NewPage(DESTINATION)<br /> SetString(destinationPage, &quot;message&quot;, &quot;Please indicate where you want to install the files .&quot;)<br /> SetString(destinationPage, &quot;destination&quot;, &quot;SYS:&quot;)<br /> <br /> # Define a directory to be copied to the destination<br /> filePack = AddPackage (FILEPACKAGE,<br /> name = &quot;Full directory&quot;,<br /> description = &quot;Directory to copy as-is in the destination&quot;,<br /> files = [&quot;data&quot;],<br /> optional = False<br /> )<br /> <br /> # Define a progress page that is shown during the installation<br /> installPage = NewPage(INSTALL)<br /> <br /> # Create a &quot;finish&quot; page.<br /> finalPage = NewPage(FINISH)<br /> SetString(finalPage, &quot;message&quot;, finishText)<br /> <br /> # Finally, this runs the installation.<br /> RunInstaller()<br /> &lt;/pre&gt;<br /> <br /> = Python Interface =<br /> <br /> == Introduction ==<br /> <br /> The installer is entirely programmed in Python. For this purpose, it provides a Python module called 'installer' that serves as a functional interface to the GUI. The entire GUI is build out of pages. Pages present different kind of information to the user. The installation can be navigated with a pair of forward/backward buttons to visit each page in turn. Certain pages (notably the INSTALL page) will trigger the installation process itself, although the interface is flexible enough to make an installation that is entirely driven by the Python script. A minimal setup function will create a &quot;default&quot; layout of pages for an installer. The basic is to have a single archive that is installed into a destination drawer created on the disk - about 90% of all installers will do exactly this. Therefore a lot of the mechanics involved in this type of installer is automated.<br /> <br /> == Python Functions in the installer package ==<br /> <br /> === NewPage ===<br /> <br /> This function creates a new page and returns its page number for later reference. The only argument to the function is the type of page to create. Possible values are:<br /> <br /> ; WELCOME<br /> : A message page, usually used for displaying a &quot;welcome&quot; message, although other uses are perfectly possible as well.<br /> : ''Note:'' this page is mandatory.<br /> <br /> ; FINISH<br /> : A message page that is specifically targeted at closing the installation. This page automatically gets the &quot;finish&quot; attribute set to make the installation change the &quot;cancel&quot; to the &quot;finish&quot; button.<br /> <br /> ; DESTINATION<br /> : A page to select a directory to serve as the target for the installation.<br /> : ''Note:'' this page is mandatory.<br /> <br /> ; INSTALL<br /> : The presence of this page automatically triggers the installation of the selected packages.<br /> <br /> ; GUI<br /> : A page where GUI elements can be added and controlled via a Python handler.<br /> <br /> ; PROCESSING<br /> : A page to display a simple progress bar for doing some Python-scripted processing.<br /> <br /> ; LICENSE<br /> : A brickwall page that displays a license agreement that only lets the user continue after accepting the license.<br /> : ''Note:'' the installation utility will look for a text file called &quot;license_''languagename''.language.txt&quot;, if not found, it will look for a file called &quot;license.txt&quot;.<br /> <br /> ; README<br /> : A page that displays a text file from disk for reference/README purposes.<br /> <br /> If the page cannot be generated, an OSError exception is raised.<br /> <br /> === GotoPage ===<br /> <br /> This function accepts a single argument, the page to display. This function should rarely be needed.<br /> <br /> === SetString, SetInteger, SetObject ===<br /> <br /> This function sets a variable of the specified type on a page. It accepts three parameters:<br /> * # The Page number to set the variable on<br /> * # The name of the variable<br /> * # The variable content.<br /> <br /> === GetString, GetInteger, GetObject ===<br /> <br /> These functions are the reverse of the above - they read a variable from the page specified as its first argument and the name specified as the second argument. They return a default value if the name was not found.<br /> <br /> === RunInstaller ===<br /> <br /> This function runs the installer's main loop, and needs to be the last command in an installation. Any subsequent scripting is done via handlers connected to the pages.<br /> <br /> === AddPackage ===<br /> <br /> This function adds a package to the list of installable packages. The function's interface uses keywords to make it more readable. The keywords are<br /> <br /> ; type<br /> : The type of package. This can be either FILEPACKAGE, ARCHIVEPACKAGE or HANDLERPACKAGE. A file package copies a list of files to the destination. An archive package unpacks a list of archives at the destination. Finally, a handler package is an abstract package that executes a handler when it is installed or upon certain actions.<br /> : This argument MUST be given.<br /> <br /> ; name<br /> : A string that specifies the name of the package. This name is presented to the user of the installer on a PACKAGESELECT page.<br /> : A name should be given. It defaults to an empty string.<br /> <br /> ; description<br /> : A textual description of the package. It is presented to the user next to the package list on a PACKAGESELECT page if the package is selected in the package list.<br /> : The description may be empty, although it is consider bad style. It defaults to an empty string.<br /> <br /> ; optional<br /> : A boolean value indicating whether the package is optional to install or required to be installed. A value of True means the package is optional.<br /> : Default is True (package is optional)<br /> <br /> ; selected<br /> : A boolean indicating whether the package should be pre-selected or not. If True, the package is selected the first time the PACKAGESELECT page is entered.<br /> : Default is True (package is selected), although the user might deselect the package on a PACKAGESELECT page<br /> <br /> ; diskspace<br /> : An integer value specifying the number of bytes the package occupies after installation. If a zero size is given (or the parameter is omitted) the installer tries to figure out the size requirements automatically, but be warned this might be a time consuming process.<br /> : Defaults to zero (try to figure out yourself)<br /> <br /> ; featuregroup<br /> : An integer bitmask giving one bit of each feature group defined. A one bit indicates this package is part of the group, while a zero bit indicates it isn't.<br /> : Defaults to zero (not in any feature group)<br /> <br /> ; alternatepath<br /> : Specifies an alternative installation path. For example, some files might need to be installed into LIBS: instead of the usual destination. This feature should be used with care.<br /> : Defaults to None (i.e. no alternate path)<br /> <br /> ; files<br /> : A list of strings, each string representing one file associated with this package. The interpretation of these files depend on the package type:<br /> :: ARCHIVEPACKAGE: each file is an archive that is supposed to be extracted into the destination.<br /> :: HANDLERPACKAGE: The strings are not interpreted in any way, it is up to the handler to do that.<br /> :: FILEPACKAGE: Each string stands for a file or directory to be copied. Files are straight copies, while directory names are interpreted slightly different: if a directory name is given, that entire directory is copied to the destination, including the directory itself. For example, if you specify &quot;System&quot; then the destination directory will include a &quot;System&quot; directory. On the other hand, if you specify it as &quot;System/&quot; with a trailing slash, the content of the directory will be copied but not the directory itself, i.e. the destination directory would contain all the file and directories in the &quot;System&quot; directory but not the directory itself.<br /> :: ''Note:'' directory/file names must be relative to the current directory i.e. where the installer is executed. You cannot use here a complete path name with the volume name like ''RAM:mydir''.<br /> : The default is an empty list.<br /> <br /> The result of this function is a package number, which can be used subsequently to adjust package settings or query certain features.<br /> <br /> == GUI's ==<br /> <br /> GUI's must be created from scratch using a procedural interface. The following procedures deal with creating and handling the user interface. In general, the user interface must be generated once and cannot be changed afterwards (with exceptions, see below).<br /> <br /> A GUI is started with a call to StartGUI(page_number). This will start to create a GUI on the indicated page number, and all subsequent calls will add to this GUI until EndGUI() is called. If the indicated page number is invalid or is not a GUI page, ever subsequent calls are ignored until a new StartGUI with a valid page number is called.<br /> <br /> Immediately after the call, a single GUI object might be defined. In almost all cases, this will be a group to hold a number of GUI elements. Groups are defined with the BeginGroup and EndGroup calls.<br /> <br /> BeginGroup takes the following keyword arguments:<br /> ; orientation<br /> : This specifies whether the children of this group are laid out vertically or horizontally. By default the layout is vertically.<br /> ; label<br /> : A short text string that can be displayed as a label for this group. The label is only used if a frame other than NONE_FRAME is specified. By default no label is used.<br /> ; frame<br /> : One of the constants NONE_FRAME, THIN_FRAME, BUTTON_FRAME, GROUP_FRAME, FIELD_FRAME, DROPBOX_FRAME, SBAR_HORIZ_FRAME, SBAR_VERT_FRAME, BOX_FRAME, STANDARD_FRAME. They directly correspond to the bevel styles of bevel.image. Defaults to NONE_FRAME.<br /> ; weight<br /> : An integer defining the weighted width or height of this group. This corresponds to layout.gadget's CHILD_WeightedWidth or CHILD_WeightedHeight tags, depending on the layout direction.<br /> <br /> EndGroup has no parameters and automatically terminates the last group opened by BeginGroup.<br /> <br /> User interface elements are added with the following calls. All of these return an ID number.<br /> <br /> === AddLabel ===<br /> <br /> This call adds a text label, with selectable frame. The following keyword arguments are supported:<br /> ; label<br /> : A string that specifies the label to be displayed. Default is empty, although an empty label doesn't make much sense<br /> <br /> ; weight<br /> : The weight of the label, as explained above.<br /> <br /> ; frame<br /> : A frame to put around the label.<br /> <br /> === AddButton ===<br /> <br /> This call adds a push button object to the current group. The function supports the following keyword arguments:<br /> ; label<br /> : A string specifying the label to be displayed within the button. Defaults to an empty label.<br /> <br /> ; frame<br /> : One of the constants mentioned above for the group. Defaults to BUTTON_FRAME.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; onclick<br /> : A Python callable object that is invoked when the button is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id) where page_number is the page number of the GUI page and element_id is the element id returned by this call.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddCheckBox ===<br /> <br /> This call adds a checkbox object to the GUI. The following keyword arguments are valid:<br /> <br /> ; label<br /> : A string that appears as a label to the right of the checkbox. Defaults to an empty label.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; checked<br /> : An integer that specifies whether the checkbox is initially checked or not. A zero means the checkbox is clear, any other value says the box is checked.<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the checkbox is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, state) where page_number and element_id are the same as above, and state is a 0 if the user just unchecked the checkbox, or a 1 is it was just checked.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddRadioButton ===<br /> <br /> This call adds a set of mutually exclusive radio buttons. The following keyword arguments are valid:<br /> <br /> ; labels<br /> : A list of Python strings, with each of these strings appearing as a choice on the Radio buttons. This parameter is required.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; selected<br /> : The number of the button initially selected. Defaults to the first button (0).<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the radio button is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the button number that was selected.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddChooser ===<br /> <br /> This function adds a chooser gadget to the GUI. The following keyword arguments are valid:<br /> <br /> ; label<br /> : A test string to be displayed in the chooser in pop-up mode (see below). Defaults to an empty string, and is not used for drop-down mode.<br /> <br /> ; choices<br /> : A list of text strings to be displayed as choices for the chooser. This argument is mandatory.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; selected<br /> : The number of the currently visible item in drop-down mode. Defaults to 0.<br /> <br /> ; mode: One of the constants CHOOSER_POPUP or CHOOSER_DROPDOWN. This corresponds to the chooser.gadget CHOOSER_PopUp and CHOOSER_DropDown tag items.<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the chooser is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the title number that was selected.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddSpace ===<br /> <br /> This call adds a bit of space to the GUI. It accepts only one parameter:<br /> <br /> ; weight<br /> : An integer specifying the weight of the space. Defaults to 1.<br /> <br /> The call does not return a value. Space does not have any variables.<br /> <br /> == User Interface Settings ==<br /> <br /> In order to change some aspects of user interface elements (like the selection status of a checkbox) or read their current state, two functions exist called GetUIAttr and SetUIAttr.<br /> <br /> The former reads an attribute from an identified user interface element (identified by the page number and element id) while the latter sets (and updates the on-screen representation) of an equally identified element.<br /> <br /> A number of attributes can be set and gotten from UI elements; some of them are shared among more than one element type, while others are specific. The following list names the attributes:<br /> <br /> ; GUI_LABEL (string)<br /> : The label displayed on a UI element.<br /> : Applies to BUTTON, LABEL, GROUP, CHECKBOX<br /> <br /> ; GUI_SELECTED (integer)<br /> : The selected item in a chooser or radio button.<br /> : Applies to CHOOSER and RADIOBUTTON<br /> <br /> ; GUI_CHECKED (integer)<br /> : Whether the checkbox checkmark is set or not.<br /> : Applies to CHECKBOX<br /> <br /> ; GUI_ONCLICK (Python callable)<br /> : The handler invoked when the UI element is activated.<br /> : Applies to CHOOSER, BUTTON, LABEL, GROUP, CHECKBOX, RADIOBUTTON<br /> <br /> The GetUIAttr function's prototype looks like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> result = GetUIAttr(page_nr, id, attr)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> page_nr and id identify the object by giving the GUI's page number and the element id returned by the creation call. The attr parameter is one of the attributes given above. Valid parameters for attr are GUI_SELECTED, GUI_CHECKED and GUI_ONCLICK.<br /> <br /> For SetUIAttr, the prototype looks like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> SetUIAttr(page_nr, id, attr, value)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> page_nr and id and attr are the same as above. The value parameter specifies the new value of the attribute, and must match the type for the attribute or the call will have no effect.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=Installation_Utility&diff=6283 Installation Utility 2013-08-03T19:23:55Z <p>Philippe Ferrucci: /* Example script */ PACKAGESELECT crashes right now</p> <hr /> <div>= How the installer works =<br /> <br /> == Basic concept ==<br /> <br /> The installation utility executes a python script that sets up the installation. In addition to standard Python commands the installation utility provides a module called &quot;installer&quot; and an interface to it. Using this interface you can create the different pages that can be found in almost all installation processes: a welcome page, a displayed licence page, a selection page, an installation page and finally a finish page.<br /> In the end, there are only a few script commands required.<br /> <br /> == Running an installation script ==<br /> <br /> === From the command line ===<br /> <br /> In order to run an installation from the command line, invoke the installation utility giving your script file as an argument and if you want a logo to be displayed at the top of the window:<br /> <br /> &lt;pre&gt;<br /> &quot;SYS:Utilities/Installation utility&quot; PACKAGE=myscript.py LOGO=mylogo.png<br /> &lt;/pre&gt;<br /> Note: the logo will be displayed all along the installation process.<br /> <br /> ''Note2: right now you need to set these argument names with capital letters, as shown above.''<br /> <br /> === From the Workbench ===<br /> <br /> Add a project icon to your script and use ''SYS:Utilities/Installation utility'' as the default tool.<br /> <br /> ==== Tooltypes ====<br /> <br /> * PACKAGE (Default: ''package.py'')<br /> <br /> This tooltype is used to specify the script name to execute. It is useful if you want to use a standalone icon that will open a script with a different name or in another directory.<br /> <br /> * LOGO<br /> <br /> You can use this tooltype to specify an image name to use in the installer window.<br /> <br /> = Example script =<br /> <br /> A minimal install script looks like this:<br /> <br /> &lt;pre&gt;<br /> # Simple, basic installation script<br /> from installer import *<br /> <br /> # These will be used for the first page (welcome) and last page (finish)<br /> welcomeText = &quot;This is a welcome text, displayed at the first page&quot;<br /> finishText = &quot;This is the finish message&quot;<br /> <br /> # Define the Welcome page<br /> welcomePage = NewPage(WELCOME)<br /> SetString(welcomePage, &quot;message&quot;, welcomeText)<br /> <br /> # Define the License page. The user must accept this license to continue the install process.<br /> # The license text will be read from a text file called &quot;license.txt&quot; and will be displayed on the page.<br /> licensePage = NewPage(LICENSE)<br /> <br /> # Define a page to select the installation directory<br /> destinationPage = NewPage(DESTINATION)<br /> SetString(destinationPage, &quot;message&quot;, &quot;Please indicate where you want to install the files .&quot;)<br /> SetString(destinationPage, &quot;destination&quot;, &quot;SYS:&quot;)<br /> <br /> # Define a progress page that is shown during the installation<br /> installPage = NewPage(INSTALL)<br /> <br /> # Create a &quot;finish&quot; page.<br /> finalPage = NewPage(FINISH)<br /> SetString(finalPage, &quot;message&quot;, finishText)<br /> <br /> # Finally, this runs the installation.<br /> RunInstaller()<br /> &lt;/pre&gt;<br /> <br /> = Python Interface =<br /> <br /> == Introduction ==<br /> <br /> The installer is entirely programmed in Python. For this purpose, it provides a Python module called 'installer' that serves as a functional interface to the GUI. The entire GUI is build out of pages. Pages present different kind of information to the user. The installation can be navigated with a pair of forward/backward buttons to visit each page in turn. Certain pages (notably the INSTALL page) will trigger the installation process itself, although the interface is flexible enough to make an installation that is entirely driven by the Python script. A minimal setup function will create a &quot;default&quot; layout of pages for an installer. The basic is to have a single archive that is installed into a destination drawer created on the disk - about 90% of all installers will do exactly this. Therefore a lot of the mechanics involved in this type of installer is automated.<br /> <br /> == Python Functions in the installer package ==<br /> <br /> === NewPage ===<br /> <br /> This function creates a new page and returns its page number for later reference. The only argument to the function is the type of page to create. Possible values are:<br /> <br /> ; WELCOME<br /> : A message page, usually used for displaying a &quot;welcome&quot; message, although other uses are perfectly possible as well.<br /> : ''Note:'' this page is mandatory.<br /> <br /> ; FINISH<br /> : A message page that is specifically targeted at closing the installation. This page automatically gets the &quot;finish&quot; attribute set to make the installation change the &quot;cancel&quot; to the &quot;finish&quot; button.<br /> <br /> ; DESTINATION<br /> : A page to select a directory to serve as the target for the installation.<br /> : ''Note:'' this page is mandatory.<br /> <br /> ; INSTALL<br /> : The presence of this page automatically triggers the installation of the selected packages.<br /> <br /> ; GUI<br /> : A page where GUI elements can be added and controlled via a Python handler.<br /> <br /> ; PROCESSING<br /> : A page to display a simple progress bar for doing some Python-scripted processing.<br /> <br /> ; LICENSE<br /> : A brickwall page that displays a license agreement that only lets the user continue after accepting the license.<br /> : ''Note:'' the installation utility will look for a text file called &quot;license_''languagename''.language.txt&quot;, if not found, it will look for a file called &quot;license.txt&quot;.<br /> <br /> ; README<br /> : A page that displays a text file from disk for reference/README purposes.<br /> <br /> If the page cannot be generated, an OSError exception is raised.<br /> <br /> === GotoPage ===<br /> <br /> This function accepts a single argument, the page to display. This function should rarely be needed.<br /> <br /> === SetString, SetInteger, SetObject ===<br /> <br /> This function sets a variable of the specified type on a page. It accepts three parameters:<br /> * # The Page number to set the variable on<br /> * # The name of the variable<br /> * # The variable content.<br /> <br /> === GetString, GetInteger, GetObject ===<br /> <br /> These functions are the reverse of the above - they read a variable from the page specified as its first argument and the name specified as the second argument. They return a default value if the name was not found.<br /> <br /> === RunInstaller ===<br /> <br /> This function runs the installer's main loop, and needs to be the last command in an installation. Any subsequent scripting is done via handlers connected to the pages.<br /> <br /> === AddPackage ===<br /> <br /> This function adds a package to the list of installable packages. The function's interface uses keywords to make it more readable. The keywords are<br /> <br /> ; type<br /> : The type of package. This can be either FILEPACKAGE, ARCHIVEPACKAGE or HANDLERPACKAGE. A file package copies a list of files to the destination. An archive package unpacks a list of archives at the destination. Finally, a handler package is an abstract package that executes a handler when it is installed or upon certain actions.<br /> : This argument MUST be given.<br /> <br /> ; name<br /> : A string that specifies the name of the package. This name is presented to the user of the installer on a PACKAGESELECT page.<br /> : A name should be given. It defaults to an empty string.<br /> <br /> ; description<br /> : A textual description of the package. It is presented to the user next to the package list on a PACKAGESELECT page if the package is selected in the package list.<br /> : The description may be empty, although it is consider bad style. It defaults to an empty string.<br /> <br /> ; optional<br /> : A boolean value indicating whether the package is optional to install or required to be installed. A value of True means the package is optional.<br /> : Default is True (package is optional)<br /> <br /> ; selected<br /> : A boolean indicating whether the package should be pre-selected or not. If True, the package is selected the first time the PACKAGESELECT page is entered.<br /> : Default is True (package is selected), although the user might deselect the package on a PACKAGESELECT page<br /> <br /> ; diskspace<br /> : An integer value specifying the number of bytes the package occupies after installation. If a zero size is given (or the parameter is omitted) the installer tries to figure out the size requirements automatically, but be warned this might be a time consuming process.<br /> : Defaults to zero (try to figure out yourself)<br /> <br /> ; featuregroup<br /> : An integer bitmask giving one bit of each feature group defined. A one bit indicates this package is part of the group, while a zero bit indicates it isn't.<br /> : Defaults to zero (not in any feature group)<br /> <br /> ; alternatepath<br /> : Specifies an alternative installation path. For example, some files might need to be installed into LIBS: instead of the usual destination. This feature should be used with care.<br /> : Defaults to None (i.e. no alternate path)<br /> <br /> ; files<br /> : A list of strings, each string representing one file associated with this package. The interpretation of these files depend on the package type:<br /> :: ARCHIVEPACKAGE: each file is an archive that is supposed to be extracted into the destination.<br /> :: HANDLERPACKAGE: The strings are not interpreted in any way, it is up to the handler to do that.<br /> :: FILEPACKAGE: Each string stands for a file or directory to be copied. Files are straight copies, while directory names are interpreted slightly different: if a directory name is given, that entire directory is copied to the destination, including the directory itself. For example, if you specify &quot;System&quot; then the destination directory will include a &quot;System&quot; directory. On the other hand, if you specify it as &quot;System/&quot; with a trailing slash, the content of the directory will be copied but not the directory itself, i.e. the destination directory would contain all the file and directories in the &quot;System&quot; directory but not the directory itself.<br /> :: ''Note:'' directory/file names must be relative to the current directory i.e. where the installer is executed. You cannot use here a complete path name with the volume name like ''RAM:mydir''.<br /> : The default is an empty list.<br /> <br /> The result of this function is a package number, which can be used subsequently to adjust package settings or query certain features.<br /> <br /> == GUI's ==<br /> <br /> GUI's must be created from scratch using a procedural interface. The following procedures deal with creating and handling the user interface. In general, the user interface must be generated once and cannot be changed afterwards (with exceptions, see below).<br /> <br /> A GUI is started with a call to StartGUI(page_number). This will start to create a GUI on the indicated page number, and all subsequent calls will add to this GUI until EndGUI() is called. If the indicated page number is invalid or is not a GUI page, ever subsequent calls are ignored until a new StartGUI with a valid page number is called.<br /> <br /> Immediately after the call, a single GUI object might be defined. In almost all cases, this will be a group to hold a number of GUI elements. Groups are defined with the BeginGroup and EndGroup calls.<br /> <br /> BeginGroup takes the following keyword arguments:<br /> ; orientation<br /> : This specifies whether the children of this group are laid out vertically or horizontally. By default the layout is vertically.<br /> ; label<br /> : A short text string that can be displayed as a label for this group. The label is only used if a frame other than NONE_FRAME is specified. By default no label is used.<br /> ; frame<br /> : One of the constants NONE_FRAME, THIN_FRAME, BUTTON_FRAME, GROUP_FRAME, FIELD_FRAME, DROPBOX_FRAME, SBAR_HORIZ_FRAME, SBAR_VERT_FRAME, BOX_FRAME, STANDARD_FRAME. They directly correspond to the bevel styles of bevel.image. Defaults to NONE_FRAME.<br /> ; weight<br /> : An integer defining the weighted width or height of this group. This corresponds to layout.gadget's CHILD_WeightedWidth or CHILD_WeightedHeight tags, depending on the layout direction.<br /> <br /> EndGroup has no parameters and automatically terminates the last group opened by BeginGroup.<br /> <br /> User interface elements are added with the following calls. All of these return an ID number.<br /> <br /> === AddLabel ===<br /> <br /> This call adds a text label, with selectable frame. The following keyword arguments are supported:<br /> ; label<br /> : A string that specifies the label to be displayed. Default is empty, although an empty label doesn't make much sense<br /> <br /> ; weight<br /> : The weight of the label, as explained above.<br /> <br /> ; frame<br /> : A frame to put around the label.<br /> <br /> === AddButton ===<br /> <br /> This call adds a push button object to the current group. The function supports the following keyword arguments:<br /> ; label<br /> : A string specifying the label to be displayed within the button. Defaults to an empty label.<br /> <br /> ; frame<br /> : One of the constants mentioned above for the group. Defaults to BUTTON_FRAME.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; onclick<br /> : A Python callable object that is invoked when the button is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id) where page_number is the page number of the GUI page and element_id is the element id returned by this call.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddCheckBox ===<br /> <br /> This call adds a checkbox object to the GUI. The following keyword arguments are valid:<br /> <br /> ; label<br /> : A string that appears as a label to the right of the checkbox. Defaults to an empty label.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; checked<br /> : An integer that specifies whether the checkbox is initially checked or not. A zero means the checkbox is clear, any other value says the box is checked.<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the checkbox is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, state) where page_number and element_id are the same as above, and state is a 0 if the user just unchecked the checkbox, or a 1 is it was just checked.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddRadioButton ===<br /> <br /> This call adds a set of mutually exclusive radio buttons. The following keyword arguments are valid:<br /> <br /> ; labels<br /> : A list of Python strings, with each of these strings appearing as a choice on the Radio buttons. This parameter is required.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; selected<br /> : The number of the button initially selected. Defaults to the first button (0).<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the radio button is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the button number that was selected.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddChooser ===<br /> <br /> This function adds a chooser gadget to the GUI. The following keyword arguments are valid:<br /> <br /> ; label<br /> : A test string to be displayed in the chooser in pop-up mode (see below). Defaults to an empty string, and is not used for drop-down mode.<br /> <br /> ; choices<br /> : A list of text strings to be displayed as choices for the chooser. This argument is mandatory.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; selected<br /> : The number of the currently visible item in drop-down mode. Defaults to 0.<br /> <br /> ; mode: One of the constants CHOOSER_POPUP or CHOOSER_DROPDOWN. This corresponds to the chooser.gadget CHOOSER_PopUp and CHOOSER_DropDown tag items.<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the chooser is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the title number that was selected.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddSpace ===<br /> <br /> This call adds a bit of space to the GUI. It accepts only one parameter:<br /> <br /> ; weight<br /> : An integer specifying the weight of the space. Defaults to 1.<br /> <br /> The call does not return a value. Space does not have any variables.<br /> <br /> == User Interface Settings ==<br /> <br /> In order to change some aspects of user interface elements (like the selection status of a checkbox) or read their current state, two functions exist called GetUIAttr and SetUIAttr.<br /> <br /> The former reads an attribute from an identified user interface element (identified by the page number and element id) while the latter sets (and updates the on-screen representation) of an equally identified element.<br /> <br /> A number of attributes can be set and gotten from UI elements; some of them are shared among more than one element type, while others are specific. The following list names the attributes:<br /> <br /> ; GUI_LABEL (string)<br /> : The label displayed on a UI element.<br /> : Applies to BUTTON, LABEL, GROUP, CHECKBOX<br /> <br /> ; GUI_SELECTED (integer)<br /> : The selected item in a chooser or radio button.<br /> : Applies to CHOOSER and RADIOBUTTON<br /> <br /> ; GUI_CHECKED (integer)<br /> : Whether the checkbox checkmark is set or not.<br /> : Applies to CHECKBOX<br /> <br /> ; GUI_ONCLICK (Python callable)<br /> : The handler invoked when the UI element is activated.<br /> : Applies to CHOOSER, BUTTON, LABEL, GROUP, CHECKBOX, RADIOBUTTON<br /> <br /> The GetUIAttr function's prototype looks like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> result = GetUIAttr(page_nr, id, attr)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> page_nr and id identify the object by giving the GUI's page number and the element id returned by the creation call. The attr parameter is one of the attributes given above. Valid parameters for attr are GUI_SELECTED, GUI_CHECKED and GUI_ONCLICK.<br /> <br /> For SetUIAttr, the prototype looks like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> SetUIAttr(page_nr, id, attr, value)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> page_nr and id and attr are the same as above. The value parameter specifies the new value of the attribute, and must match the type for the attribute or the call will have no effect.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=AmiDock_and_Dockies&diff=6282 AmiDock and Dockies 2013-08-03T18:29:08Z <p>Philippe Ferrucci: </p> <hr /> <div>= Introduction =<br /> <br /> AmiDock is a toolbar system. It is a commodity program that will stay on the Workbench screen. Amidock allows the user to always have at hand program icons or to keep an eye on some information. This way it is very easy to run a program: one click is enough. Also Amidock can host some small programs that displays some information. The user can then get these information in a blink of an eye.<br /> <br /> = What are a Dock and a Docky? =<br /> <br /> == Dock ==<br /> A Dock is an area/a window (currently provided by the &quot;AmiDock&quot; commodity) where the user can put some icons and other stuff. Some may call it &quot;Panels&quot;. <br /> <br /> <br /> So, Docks can be used as Launcher Panels:<br /> <br /> <br /> [[File:Laucher_dock.png|center]]<br /> <br /> <br /> And as Tray Bar panels:<br /> <br /> [[File:Tray_doc.jpg|center]]<br /> <br /> <br /> As anything else anyone can come up with: you can put everything inside of panels of any size, structure and design it as you wish.<br /> <br /> == Docky ==<br /> <br /> A Docky is this item the user can place in the dock: a program icon or an interactive program. Dockies are able to control most of AmiDocks feature and provide a great way to expand AmiDocks features beyond its default features. Dockies may be invisible to the user or show static or dynamic (animated) content. You may change their behavior, size and look acording their current equirements. Dockies can be of 2 main types:<br /> <br /> '''Standalone Dockies'''.<br /> <br /> Is a special type of program which is made to show an icon in a Dock, delivering some functionality to the user. It is the most common form of Dockies. This docky-type uses the shared library feature of AmigaOS4 as common interface to the internal properties and behavioral possibilities of a docky.<br /> <br /> '''Application Dockies'''.<br /> <br /> That second type of dockies are application dockies (short form 'AppDockies' or as some call it 'AppDockIcon Dockies'). An AppDocky is a docky which is introduced to the system during runtime by an application using application.library registration mechanism for applications. The biggest diference between the two docky types is that AppDockies belong to a running application and usually are used to represent the current state of the owning application.<br /> <br /> To sum up in &quot;standalone dockies&quot; the docky itself is the application (the only reason of existence of the application is the docky) while for &quot;AppDockIcon dockies&quot; the docky is just a graphical representation of a bigger application (the docky is just here to add user friendliness or visual feedback of the surrounding application)<br /> <br /> ==== Dockies provided with AmigaOS4 ====<br /> <br /> ===== Access.docky =====<br /> <br /> Single click with the left mouse button on this docky to open a list of screens and windows. Select a window and it will be activated and come to front (optionally). This docky especially is cool when using a hotkey - this way you can use the popup on EVERY screen. Just specify the hotkey like you do it with normal icons, too. Use the context menu to toggle to-front mode<br /> <br /> ===== Anim.docky =====<br /> <br /> On a empty Anim.docky (no Animation assigned yet), drop a GIF-Animation (e.g. Boing#?.gif) on this dockie to change the current animation(in a selected dock) point with the mouse pointer over the docky and press the &quot;+&quot;/&quot;-&quot;-Keys to change animation speed. Use the context menu to specify a tool which shall be combined with this docky. You can also change the used animation here.<br /> <br /> ===== Button.docky =====<br /> <br /> On a empty Button.docky (no Picture assigned yet), drop a picture on this docky to change the current image. Use the context menu to specify a tool which shall be combined with this docky. You can also change the used picture here.<br /> <br /> ===== Clock.docky =====<br /> <br /> A analog clock in the dock. This docky changes automatically to a digital clock if you change to name or button style docks. Double click the docky or use the context menu to open the system time preferences.<br /> <br /> ===== Debugger.docky =====<br /> <br /> This docky opens a window and shows debugging information for docky-programmers. Needed only for people developing third-party dockies. Single-click it to enable/disable debug mode. Debugger.docky saves its state in its preferences. Use the context menu to toggle between single-dock and global (all docks) debugging.<br /> <br /> ===== Lens.docky =====<br /> <br /> Double click this docky to switch between normal or maximized view<br /> <br /> Note: Normal and maximized view do have their own settings. Do that in a selected dock:<br /> <br /> point with the mouse pointer over the docky and press the key &quot;x&quot; - this will toggle between &quot;cross-hair&quot; mode and non-cross-hair mode.<br /> point with the mouse pointer over the docky and press the &quot;+&quot;/&quot;-&quot;-Keys to change the used magnification<br /> point with the mouse pointer over the docky and press the key &quot;c&quot; to enable coordinates<br /> point with the mouse pointer over the docky and press the key &quot;v&quot; to enable RGB values output (only available in a maximized lens!!)<br /> point with the mouse pointer over the docky and press the key &quot;g&quot; to enable/disable the grid.<br /> <br /> You can also use the context menu to change all the above described settings.<br /> <br /> ===== Minimizer.docky =====<br /> <br /> As soon as this docky was added to a dock (to make the docky &quot;invisible&quot; use another category for placing the docky), the dock will shrink to the minimized state after some time. As soon as the pointer is placed over the drag-bar, it expands to normal size. You can change the delay time until this docky minimizes the dock using the contextual menu.<br /> <br /> ===== Online.docky =====<br /> <br /> Allows you to go on- and offline with RoadShow. Not fully implemented yet!!!<br /> <br /> ===== Rainbow.docky =====<br /> <br /> This docky shows a colorful rainbow with alpha channel (!) - but nothing more. Double click it to toggle between icon and image view. This dock needs screen depth &gt;8Bit. AmiDock will deny it on screen depths below 8Bit.<br /> <br /> ===== Seperator.docky =====<br /> <br /> This docky is nothing more than just a seperator line. It automatically adjusts itself to the size and orientation of a dock.<br /> <br /> ===== SubDocks.docky =====<br /> <br /> Use the shortcut Amiga+U to place it in the current dock or throw it in the dock which shall contain it...<br /> <br /> - drag&amp;drop a icon on it to configure its icon in AmiDock<br /> - if you delete the subdock, the docky will remove itself automatically<br /> - if you delete the docky, the docky will remove the subdock itself automatically<br /> - (in a selected dock) point with the mouse pointer over the docky and press the key &quot;p&quot; to toggle between popupmode (default, closes the dock after a object was clicked) or normal mode (doesn't close the dock)<br /> - Use the context menu to toggle the popup mode and ti change the icon.<br /> <br /> ===== Test.docky =====<br /> The first docky ever written. Just a fun-docky. This docky &quot;listens&quot; to all possible events and shows this by flashing in some color when a action is detected. Move your mouse over the docky and click it. Drag&amp;Drop several files on the docky and watch what happens. This dock needs screen depth &gt;8Bit. AmiDock will deny it on screen depths below 8Bit.<br /> <br /> = AmiDock's hints =<br /> <br /> - If the Minimizeable-Checkbox is checked, you can minimize a dock by double-clicking it's drag-bar.<br /> <br /> - Bring to front/send to back can be done by double clicking on an empty area in a dock (SHIFT together with a dobule click will send it to back).<br /> <br /> - in a selected dock: shift+click+hold on a icon and move around to interactively change the icon-position<br /> <br /> - to interactively delete a icon or a whole dock: click+hold the object, press the Backspace or Delete key<br /> <br /> = AmiDock's API =<br /> <br /> = Different types of Dockies =<br /> == Standalone Dockies ==<br /> <br /> == AppDockIcon Dockies ==<br /> <br /> = How to make a right Docky =<br /> <br /> = How to make a Docky for tray-bar kind Docks =<br /> <br /> If you are a developer and you want to make your dockies to work in tray-bar kind docks, you need to make a docky more flexible, and you should follow some rules when you do it:<br /> <br /> 1. <br /> <br /> 2.<br /> <br /> 3.<br /> <br /> <br /> = FAQ =<br /> <br /> = Final Words =<br /> <br /> = Links =<br /> <br /> 1. SDK:Documentation/AutoDocs/docky.doc<br /> <br /> 2. Sys:Documentation/Commodities/AmiDock_Arexx.doc</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=AmiDock_and_Dockies&diff=6281 AmiDock and Dockies 2013-08-03T18:23:02Z <p>Philippe Ferrucci: /* Docky */</p> <hr /> <div>= Introduction =<br /> <br /> AmiDock is a toolbar system. It is a commodity program that will stay on the Workbench screen. Amidock allows the user to always have at hand program icons or to keep an eye on some information. This way it is very easy to run a program: one click is enough. Also Amidock can host some small programs that displays some information. The user can then get these information in a blink of an eye.<br /> <br /> == What is a Dock and a Docky ==<br /> <br /> === Dock ===<br /> A Dock is an area/a window (currently provided by the &quot;AmiDock&quot; commodity) where the user can put some icons and other stuff. Some may call it &quot;Panels&quot;. <br /> <br /> <br /> So, Docks can be used as Launcher Panels:<br /> <br /> <br /> [[File:Laucher_dock.png|center]]<br /> <br /> <br /> And as Tray Bar panels:<br /> <br /> [[File:Tray_doc.jpg|center]]<br /> <br /> <br /> As anything else anyone can come up with: you can put everything inside of panels of any size, structure and design it as you wish.<br /> <br /> === Docky ===<br /> <br /> A Docky is this item the user can place in the dock: a program icon or an interactive program. Dockies are able to control most of AmiDocks feature and provide a great way to expand AmiDocks features beyond its default features. Dockies may be invisible to the user or show static or dynamic (animated) content. You may change their behavior, size and look acording their current equirements. Dockies can be of 2 main types:<br /> <br /> '''Standalone Dockies'''.<br /> <br /> Is a special type of program which is made to show an icon in a Dock, delivering some functionality to the user. It is the most common form of Dockies. This docky-type uses the shared library feature of AmigaOS4 as common interface to the internal properties and behavioral possibilities of a docky.<br /> <br /> '''Application Dockies'''.<br /> <br /> That second type of dockies are application dockies (short form 'AppDockies' or as some call it 'AppDockIcon Dockies'). An AppDocky is a docky which is introduced to the system during runtime by an application using application.library registration mechanism for applications. The biggest diference between the two docky types is that AppDockies belong to a running application and usually are used to represent the current state of the owning application.<br /> <br /> To sum up in &quot;standalone dockies&quot; the docky itself is the application (the only reason of existence of the application is the docky) while for &quot;AppDockIcon dockies&quot; the docky is just a graphical representation of a bigger application (the docky is just here to add user friendliness or visual feedback of the surrounding application)<br /> <br /> = What is AmiDock =<br /> <br /> == Dockies provided with AmigaOS4 ==<br /> <br /> === Access.docky ===<br /> <br /> Single click with the left mouse button on this docky to open a list of screens and windows. Select a window and it will be activated and come to front (optionally). This docky especially is cool when using a hotkey - this way you can use the popup on EVERY screen. Just specify the hotkey like you do it with normal icons, too. Use the context menu to toggle to-front mode<br /> <br /> === Anim.docky ===<br /> <br /> On a empty Anim.docky (no Animation assigned yet), drop a GIF-Animation (e.g. Boing#?.gif) on this dockie to change the current animation(in a selected dock) point with the mouse pointer over the docky and press the &quot;+&quot;/&quot;-&quot;-Keys to change animation speed. Use the context menu to specify a tool which shall be combined with this docky. You can also change the used animation here.<br /> <br /> === Button.docky ===<br /> <br /> On a empty Button.docky (no Picture assigned yet), drop a picture on this docky to change the current image. Use the context menu to specify a tool which shall be combined with this docky. You can also change the used picture here.<br /> <br /> === Clock.docky ===<br /> <br /> A analog clock in the dock. This docky changes automatically to a digital clock if you change to name or button style docks. Double click the docky or use the context menu to open the system time preferences.<br /> <br /> === Debugger.docky ===<br /> <br /> This docky opens a window and shows debugging information for docky-programmers. Needed only for people developing third-party dockies. Single-click it to enable/disable debug mode. Debugger.docky saves its state in its preferences. Use the context menu to toggle between single-dock and global (all docks) debugging.<br /> <br /> === Lens.docky ===<br /> <br /> Double click this docky to switch between normal or maximized view<br /> <br /> Note: Normal and maximized view do have their own settings. Do that in a selected dock:<br /> <br /> point with the mouse pointer over the docky and press the key &quot;x&quot; - this will toggle between &quot;cross-hair&quot; mode and non-cross-hair mode.<br /> point with the mouse pointer over the docky and press the &quot;+&quot;/&quot;-&quot;-Keys to change the used magnification<br /> point with the mouse pointer over the docky and press the key &quot;c&quot; to enable coordinates<br /> point with the mouse pointer over the docky and press the key &quot;v&quot; to enable RGB values output (only available in a maximized lens!!)<br /> point with the mouse pointer over the docky and press the key &quot;g&quot; to enable/disable the grid.<br /> <br /> You can also use the context menu to change all the above described settings.<br /> <br /> === Minimizer.docky ===<br /> <br /> As soon as this docky was added to a dock (to make the docky &quot;invisible&quot; use another category for placing the docky), the dock will shrink to the minimized state after some time. As soon as the pointer is placed over the drag-bar, it expands to normal size. You can change the delay time until this docky minimizes the dock using the contextual menu.<br /> <br /> === Online.docky ===<br /> <br /> Allows you to go on- and offline with RoadShow. Not fully implemented yet!!!<br /> <br /> === Rainbow.docky ===<br /> <br /> This docky shows a colorful rainbow with alpha channel (!) - but nothing more. Double click it to toggle between icon and image view. This dock needs screen depth &gt;8Bit. AmiDock will deny it on screen depths below 8Bit.<br /> <br /> === Seperator.docky ===<br /> <br /> This docky is nothing more than just a seperator line. It automatically adjusts itself to the size and orientation of a dock.<br /> <br /> === SubDocks.docky ===<br /> <br /> Use the shortcut Amiga+U to place it in the current dock or throw it in the dock which shall contain it...<br /> <br /> - drag&amp;drop a icon on it to configure its icon in AmiDock<br /> - if you delete the subdock, the docky will remove itself automatically<br /> - if you delete the docky, the docky will remove the subdock itself automatically<br /> - (in a selected dock) point with the mouse pointer over the docky and press the key &quot;p&quot; to toggle between popupmode (default, closes the dock after a object was clicked) or normal mode (doesn't close the dock)<br /> - Use the context menu to toggle the popup mode and ti change the icon.<br /> <br /> === Test.docky ===<br /> The first docky ever written. Just a fun-docky. This docky &quot;listens&quot; to all possible events and shows this by flashing in some color when a action is detected. Move your mouse over the docky and click it. Drag&amp;Drop several files on the docky and watch what happens. This dock needs screen depth &gt;8Bit. AmiDock will deny it on screen depths below 8Bit.<br /> <br /> == AmiDock's hints ==<br /> <br /> - If the Minimizeable-Checkbox is checked, you can minimize a dock by double-clicking it's drag-bar.<br /> <br /> - Bring to front/send to back can be done by double clicking on an empty area in a dock (SHIFT together with a dobule click will send it to back).<br /> <br /> - in a selected dock: shift+click+hold on a icon and move around to interactively change the icon-position<br /> <br /> - to interactively delete a icon or a whole dock: click+hold the object, press the Backspace or Delete key<br /> <br /> = AmiDock's API =<br /> <br /> = Different types of Dockies =<br /> == Standalone Dockies ==<br /> <br /> == AppDockIcon Dockies ==<br /> <br /> = How to make a right Docky =<br /> <br /> = How to make a Docky for tray-bar kind Docks =<br /> <br /> If you as developer want to make your dockies to work in tray-bar kind docks, you need to make a docky more flexible, and you should follow some rulz when you do it:<br /> <br /> 1. <br /> <br /> 2.<br /> <br /> 3.<br /> <br /> <br /> = FAQ =<br /> <br /> = Final Words =<br /> <br /> = Links =<br /> <br /> 1. SDK:Documentation/AutoDocs/docky.doc<br /> <br /> 2. Sys:Documentation/Commodities/AmiDock_Arexx.doc</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=AmiDock_and_Dockies&diff=6280 AmiDock and Dockies 2013-08-03T18:18:30Z <p>Philippe Ferrucci: /* Introduction */</p> <hr /> <div>= Introduction =<br /> <br /> AmiDock is a toolbar system. It is a commodity program that will stay on the Workbench screen. Amidock allows the user to always have at hand program icons or to keep an eye on some information. This way it is very easy to run a program: one click is enough. Also Amidock can host some small programs that displays some information. The user can then get these information in a blink of an eye.<br /> <br /> == What is a Dock and a Docky ==<br /> <br /> === Dock ===<br /> A Dock is an area/a window (currently provided by the &quot;AmiDock&quot; commodity) where the user can put some icons and other stuff. Some may call it &quot;Panels&quot;. <br /> <br /> <br /> So, Docks can be used as Launcher Panels:<br /> <br /> <br /> [[File:Laucher_dock.png|center]]<br /> <br /> <br /> And as Tray Bar panels:<br /> <br /> [[File:Tray_doc.jpg|center]]<br /> <br /> <br /> As anything else anyone can come up with: you can put everything inside of panels of any size, structure and design it as you wish.<br /> <br /> === Docky ===<br /> <br /> In general, A Docky is what you place in the Dock. Dockies are able to control most of AmiDocks feature and provide a great way to expand AmiDocks features beyond its default features. Dockies may be invisible to the user or show static or dynamic (animated) ontent. The may change their behavior, size and look acoring their current equirements. Dockies can be of 2 main types:<br /> <br /> '''Standalone Dockies'''.<br /> <br /> Is a special type of program which is made to show an icon in a Dock, delivering some functionality to the user. It is the most common form of Dockies. This docky-type uses the shared library feature of AmigaOS4 as common interface to the internal properties and behavioral possibilities of a docky.<br /> <br /> '''Application Dockies'''.<br /> <br /> That second type of dockies are application dockies (short form 'AppDockies' or as some call it 'AppDockIcon Dockies'). An AppDocky is a docky which is introduced to the system during runtime by an application using application.librarries registration mechanism for applications. The biggest diference between the two docky types is that AppDockies belong to a running application and usually are used to represent the current state of the owning application.<br /> <br /> To sum up in &quot;standalone dockies&quot; the docky itself is the application (the only reason of existence of the application is the docky) while for &quot;AppDockIcon dockies&quot; the docky is just a graphical representation of a bigger application (the docky is just here to add user friendliness or visual feedback of the surrounding application)<br /> <br /> = What is AmiDock =<br /> <br /> == Dockies provided with AmigaOS4 ==<br /> <br /> === Access.docky ===<br /> <br /> Single click with the left mouse button on this docky to open a list of screens and windows. Select a window and it will be activated and come to front (optionally). This docky especially is cool when using a hotkey - this way you can use the popup on EVERY screen. Just specify the hotkey like you do it with normal icons, too. Use the context menu to toggle to-front mode<br /> <br /> === Anim.docky ===<br /> <br /> On a empty Anim.docky (no Animation assigned yet), drop a GIF-Animation (e.g. Boing#?.gif) on this dockie to change the current animation(in a selected dock) point with the mouse pointer over the docky and press the &quot;+&quot;/&quot;-&quot;-Keys to change animation speed. Use the context menu to specify a tool which shall be combined with this docky. You can also change the used animation here.<br /> <br /> === Button.docky ===<br /> <br /> On a empty Button.docky (no Picture assigned yet), drop a picture on this docky to change the current image. Use the context menu to specify a tool which shall be combined with this docky. You can also change the used picture here.<br /> <br /> === Clock.docky ===<br /> <br /> A analog clock in the dock. This docky changes automatically to a digital clock if you change to name or button style docks. Double click the docky or use the context menu to open the system time preferences.<br /> <br /> === Debugger.docky ===<br /> <br /> This docky opens a window and shows debugging information for docky-programmers. Needed only for people developing third-party dockies. Single-click it to enable/disable debug mode. Debugger.docky saves its state in its preferences. Use the context menu to toggle between single-dock and global (all docks) debugging.<br /> <br /> === Lens.docky ===<br /> <br /> Double click this docky to switch between normal or maximized view<br /> <br /> Note: Normal and maximized view do have their own settings. Do that in a selected dock:<br /> <br /> point with the mouse pointer over the docky and press the key &quot;x&quot; - this will toggle between &quot;cross-hair&quot; mode and non-cross-hair mode.<br /> point with the mouse pointer over the docky and press the &quot;+&quot;/&quot;-&quot;-Keys to change the used magnification<br /> point with the mouse pointer over the docky and press the key &quot;c&quot; to enable coordinates<br /> point with the mouse pointer over the docky and press the key &quot;v&quot; to enable RGB values output (only available in a maximized lens!!)<br /> point with the mouse pointer over the docky and press the key &quot;g&quot; to enable/disable the grid.<br /> <br /> You can also use the context menu to change all the above described settings.<br /> <br /> === Minimizer.docky ===<br /> <br /> As soon as this docky was added to a dock (to make the docky &quot;invisible&quot; use another category for placing the docky), the dock will shrink to the minimized state after some time. As soon as the pointer is placed over the drag-bar, it expands to normal size. You can change the delay time until this docky minimizes the dock using the contextual menu.<br /> <br /> === Online.docky ===<br /> <br /> Allows you to go on- and offline with RoadShow. Not fully implemented yet!!!<br /> <br /> === Rainbow.docky ===<br /> <br /> This docky shows a colorful rainbow with alpha channel (!) - but nothing more. Double click it to toggle between icon and image view. This dock needs screen depth &gt;8Bit. AmiDock will deny it on screen depths below 8Bit.<br /> <br /> === Seperator.docky ===<br /> <br /> This docky is nothing more than just a seperator line. It automatically adjusts itself to the size and orientation of a dock.<br /> <br /> === SubDocks.docky ===<br /> <br /> Use the shortcut Amiga+U to place it in the current dock or throw it in the dock which shall contain it...<br /> <br /> - drag&amp;drop a icon on it to configure its icon in AmiDock<br /> - if you delete the subdock, the docky will remove itself automatically<br /> - if you delete the docky, the docky will remove the subdock itself automatically<br /> - (in a selected dock) point with the mouse pointer over the docky and press the key &quot;p&quot; to toggle between popupmode (default, closes the dock after a object was clicked) or normal mode (doesn't close the dock)<br /> - Use the context menu to toggle the popup mode and ti change the icon.<br /> <br /> === Test.docky ===<br /> The first docky ever written. Just a fun-docky. This docky &quot;listens&quot; to all possible events and shows this by flashing in some color when a action is detected. Move your mouse over the docky and click it. Drag&amp;Drop several files on the docky and watch what happens. This dock needs screen depth &gt;8Bit. AmiDock will deny it on screen depths below 8Bit.<br /> <br /> == AmiDock's hints ==<br /> <br /> - If the Minimizeable-Checkbox is checked, you can minimize a dock by double-clicking it's drag-bar.<br /> <br /> - Bring to front/send to back can be done by double clicking on an empty area in a dock (SHIFT together with a dobule click will send it to back).<br /> <br /> - in a selected dock: shift+click+hold on a icon and move around to interactively change the icon-position<br /> <br /> - to interactively delete a icon or a whole dock: click+hold the object, press the Backspace or Delete key<br /> <br /> = AmiDock's API =<br /> <br /> = Different types of Dockies =<br /> == Standalone Dockies ==<br /> <br /> == AppDockIcon Dockies ==<br /> <br /> = How to make a right Docky =<br /> <br /> = How to make a Docky for tray-bar kind Docks =<br /> <br /> If you as developer want to make your dockies to work in tray-bar kind docks, you need to make a docky more flexible, and you should follow some rulz when you do it:<br /> <br /> 1. <br /> <br /> 2.<br /> <br /> 3.<br /> <br /> <br /> = FAQ =<br /> <br /> = Final Words =<br /> <br /> = Links =<br /> <br /> 1. SDK:Documentation/AutoDocs/docky.doc<br /> <br /> 2. Sys:Documentation/Commodities/AmiDock_Arexx.doc</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=AmiDock_and_Dockies&diff=6279 AmiDock and Dockies 2013-08-03T18:09:27Z <p>Philippe Ferrucci: </p> <hr /> <div>= Introduction =<br /> <br /> AmiDock is a toolbar system.<br /> <br /> == What is a Dock and a Docky ==<br /> <br /> === Dock ===<br /> A Dock is an area/a window (currently provided by the &quot;AmiDock&quot; commodity) where the user can put some icons and other stuff. Some may call it &quot;Panels&quot;. <br /> <br /> <br /> So, Docks can be used as Launcher Panels:<br /> <br /> <br /> [[File:Laucher_dock.png|center]]<br /> <br /> <br /> And as Tray Bar panels:<br /> <br /> [[File:Tray_doc.jpg|center]]<br /> <br /> <br /> As anything else anyone can come up with: you can put everything inside of panels of any size, structure and design it as you wish.<br /> <br /> === Docky ===<br /> <br /> In general, A Docky is what you place in the Dock. Dockies are able to control most of AmiDocks feature and provide a great way to expand AmiDocks features beyond its default features. Dockies may be invisible to the user or show static or dynamic (animated) ontent. The may change their behavior, size and look acoring their current equirements. Dockies can be of 2 main types:<br /> <br /> '''Standalone Dockies'''.<br /> <br /> Is a special type of program which is made to show an icon in a Dock, delivering some functionality to the user. It is the most common form of Dockies. This docky-type uses the shared library feature of AmigaOS4 as common interface to the internal properties and behavioral possibilities of a docky.<br /> <br /> '''Application Dockies'''.<br /> <br /> That second type of dockies are application dockies (short form 'AppDockies' or as some call it 'AppDockIcon Dockies'). An AppDocky is a docky which is introduced to the system during runtime by an application using application.librarries registration mechanism for applications. The biggest diference between the two docky types is that AppDockies belong to a running application and usually are used to represent the current state of the owning application.<br /> <br /> To sum up in &quot;standalone dockies&quot; the docky itself is the application (the only reason of existence of the application is the docky) while for &quot;AppDockIcon dockies&quot; the docky is just a graphical representation of a bigger application (the docky is just here to add user friendliness or visual feedback of the surrounding application)<br /> <br /> = What is AmiDock =<br /> <br /> == Dockies provided with AmigaOS4 ==<br /> <br /> === Access.docky ===<br /> <br /> Single click with the left mouse button on this docky to open a list of screens and windows. Select a window and it will be activated and come to front (optionally). This docky especially is cool when using a hotkey - this way you can use the popup on EVERY screen. Just specify the hotkey like you do it with normal icons, too. Use the context menu to toggle to-front mode<br /> <br /> === Anim.docky ===<br /> <br /> On a empty Anim.docky (no Animation assigned yet), drop a GIF-Animation (e.g. Boing#?.gif) on this dockie to change the current animation(in a selected dock) point with the mouse pointer over the docky and press the &quot;+&quot;/&quot;-&quot;-Keys to change animation speed. Use the context menu to specify a tool which shall be combined with this docky. You can also change the used animation here.<br /> <br /> === Button.docky ===<br /> <br /> On a empty Button.docky (no Picture assigned yet), drop a picture on this docky to change the current image. Use the context menu to specify a tool which shall be combined with this docky. You can also change the used picture here.<br /> <br /> === Clock.docky ===<br /> <br /> A analog clock in the dock. This docky changes automatically to a digital clock if you change to name or button style docks. Double click the docky or use the context menu to open the system time preferences.<br /> <br /> === Debugger.docky ===<br /> <br /> This docky opens a window and shows debugging information for docky-programmers. Needed only for people developing third-party dockies. Single-click it to enable/disable debug mode. Debugger.docky saves its state in its preferences. Use the context menu to toggle between single-dock and global (all docks) debugging.<br /> <br /> === Lens.docky ===<br /> <br /> Double click this docky to switch between normal or maximized view<br /> <br /> Note: Normal and maximized view do have their own settings. Do that in a selected dock:<br /> <br /> point with the mouse pointer over the docky and press the key &quot;x&quot; - this will toggle between &quot;cross-hair&quot; mode and non-cross-hair mode.<br /> point with the mouse pointer over the docky and press the &quot;+&quot;/&quot;-&quot;-Keys to change the used magnification<br /> point with the mouse pointer over the docky and press the key &quot;c&quot; to enable coordinates<br /> point with the mouse pointer over the docky and press the key &quot;v&quot; to enable RGB values output (only available in a maximized lens!!)<br /> point with the mouse pointer over the docky and press the key &quot;g&quot; to enable/disable the grid.<br /> <br /> You can also use the context menu to change all the above described settings.<br /> <br /> === Minimizer.docky ===<br /> <br /> As soon as this docky was added to a dock (to make the docky &quot;invisible&quot; use another category for placing the docky), the dock will shrink to the minimized state after some time. As soon as the pointer is placed over the drag-bar, it expands to normal size. You can change the delay time until this docky minimizes the dock using the contextual menu.<br /> <br /> === Online.docky ===<br /> <br /> Allows you to go on- and offline with RoadShow. Not fully implemented yet!!!<br /> <br /> === Rainbow.docky ===<br /> <br /> This docky shows a colorful rainbow with alpha channel (!) - but nothing more. Double click it to toggle between icon and image view. This dock needs screen depth &gt;8Bit. AmiDock will deny it on screen depths below 8Bit.<br /> <br /> === Seperator.docky ===<br /> <br /> This docky is nothing more than just a seperator line. It automatically adjusts itself to the size and orientation of a dock.<br /> <br /> === SubDocks.docky ===<br /> <br /> Use the shortcut Amiga+U to place it in the current dock or throw it in the dock which shall contain it...<br /> <br /> - drag&amp;drop a icon on it to configure its icon in AmiDock<br /> - if you delete the subdock, the docky will remove itself automatically<br /> - if you delete the docky, the docky will remove the subdock itself automatically<br /> - (in a selected dock) point with the mouse pointer over the docky and press the key &quot;p&quot; to toggle between popupmode (default, closes the dock after a object was clicked) or normal mode (doesn't close the dock)<br /> - Use the context menu to toggle the popup mode and ti change the icon.<br /> <br /> === Test.docky ===<br /> The first docky ever written. Just a fun-docky. This docky &quot;listens&quot; to all possible events and shows this by flashing in some color when a action is detected. Move your mouse over the docky and click it. Drag&amp;Drop several files on the docky and watch what happens. This dock needs screen depth &gt;8Bit. AmiDock will deny it on screen depths below 8Bit.<br /> <br /> == AmiDock's hints ==<br /> <br /> - If the Minimizeable-Checkbox is checked, you can minimize a dock by double-clicking it's drag-bar.<br /> <br /> - Bring to front/send to back can be done by double clicking on an empty area in a dock (SHIFT together with a dobule click will send it to back).<br /> <br /> - in a selected dock: shift+click+hold on a icon and move around to interactively change the icon-position<br /> <br /> - to interactively delete a icon or a whole dock: click+hold the object, press the Backspace or Delete key<br /> <br /> = AmiDock's API =<br /> <br /> = Different types of Dockies =<br /> == Standalone Dockies ==<br /> <br /> == AppDockIcon Dockies ==<br /> <br /> = How to make a right Docky =<br /> <br /> = How to make a Docky for tray-bar kind Docks =<br /> <br /> If you as developer want to make your dockies to work in tray-bar kind docks, you need to make a docky more flexible, and you should follow some rulz when you do it:<br /> <br /> 1. <br /> <br /> 2.<br /> <br /> 3.<br /> <br /> <br /> = FAQ =<br /> <br /> = Final Words =<br /> <br /> = Links =<br /> <br /> 1. SDK:Documentation/AutoDocs/docky.doc<br /> <br /> 2. Sys:Documentation/Commodities/AmiDock_Arexx.doc</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=Programming_in_the_Amiga_Environment&diff=6278 Programming in the Amiga Environment 2013-08-03T18:07:37Z <p>Philippe Ferrucci: /* Two Kinds of Memory */</p> <hr /> <div>{{NeedUpdate}}<br /> == Programming in the Amiga Environment ==<br /> <br /> To program in the Amiga's dynamic environment you need to understand these special features of the Amiga's design:<br /> <br /> * Multitasking (without memory protection)<br /> * Shared libraries of functions<br /> * Dynamic memory architecture (no memory map)<br /> * Operating system versions<br /> * Custom chips with DMA access (two kinds of memory)<br /> <br /> === Multitasking ===<br /> <br /> The key feature of the Amiga's operating system design is ''multitasking''. Multitasking means many programs, or tasks, reside in memory at the same time sharing system resources with one another. Programs take turns running so it appears that many programs are running simultaneously.<br /> <br /> Multitasking is based on the concept that a program spends most of its time waiting for things to happen. A program waits for events like key presses, mouse movement, or disk activity. While a program is waiting, the CPU is idle. The CPU could be used to run a different program during this idle period if there was a convenient method for rapidly switching from one program to another. This is what multitasking does.<br /> <br /> === What the System Does For You ===<br /> <br /> The Amiga uses ''preemptive multitasking'' which means that the operating system keeps track of all the tasks in memory and decides which one should run. The system checks hundreds of times per second to see which task should be run based on whether or not it is waiting, and other factors. Since the system handles all the work of task switching, multitasking is transparent to the application. From the application's point of view, it appears to have the machine all to itself.<br /> <br /> The Amiga OS also manages the sharing of resources between tasks. This is important because in order for a variety of tasks to run independently in the Amiga's multitasking environment, tasks must be prevented from interfering with one another. Imagine if five tasks were allowed to use the parallel port at the same time. The result would be I/O chaos. To prevent this, the operating system provides an arbitration method (usually a function call) for every system resource. For instance you must call a function, AllocMem(), to get exclusive access to a block of memory.<br /> <br /> === What the System Doesn't Do For You ===<br /> <br /> The Amiga operating system handles most of the housekeeping needed for multitasking, but this does not mean that applications don't have to worry about multitasking at all. The current generation of Amiga systems do not have hardware memory protection, so there is nothing to stop a task from using memory it has not legally acquired. An errant task can easily corrupt some other task by accidentally overwriting its instructions or data. Amiga programmers need to be extra careful with memory; one bad memory pointer can cause the machine to crash (debugging utilities such as MungWall and Enforcer will prevent this).<br /> <br /> In fact, Amiga programmers need to be careful with every system resource, not just memory. All system resources from audio channels to the floppy disk drives are shared among tasks. Before using a resource, you must ask the system for access to the resource. This may fail if the resource is already being used by another task. Once you have control of a resource, no other task can use it, so give it up as soon as you are finished. When your program exits, you must give everything back whether it's memory, access to a file, or an I/O port. You are responsible for this, the system will not do it for you automatically.<br /> <br /> {{Note|title=What Every Amiga Programmer Should Know|text=The Amiga is a ''multitasking'' computer. Keep in mind that other tasks are running at the same time as your application. Always ask the system for control of any resource you need; some other task may already be using it. Give it back as soon as you are done; another task may want to use it. This applies to just about every computing activity your application can perform.}}<br /> <br /> === Libraries of functions ===<br /> <br /> Most of the routines that make up the Amiga's operating system are organized into groups called libraries. Each library then contains one or more interfaces. In order to call a function on the Amiga you must first open the library that contains the function. Next, you get the interface which contains the function you want to call. For example, if you want to call the Read() function to read data from disk you must first open the [[AmigaDOS Introduction|DOS]] library and then get the &quot;main&quot; interface the Read() function is defined in.<br /> <br /> The system's master library, called [[Exec]], is always open. [[Exec]] keeps track of all the other [[Exec Libraries|libraries]] and is in charge of opening and closing them. [[Exec]]'s &quot;main&quot; interface contains the OpenLibrary() function which is used to open all the other libraries.<br /> <br /> Almost any program you write for the Amiga will have to call the OpenLibrary() and GetInterface() functions. Usage is as follows:<br /> <br /> &lt;syntaxhighlight&gt;<br /> // Global: declare this above main()<br /> struct Library *LibBase;<br /> struct Interface *LibIFace;<br /> <br /> int main()<br /> {<br /> LibBase = IExec-&gt;OpenLibrary(&quot;library.name&quot;, libversion);<br /> if(LibIFace == NULL)<br /> {<br /> // Library did not open, so exit.<br /> }<br /> else<br /> {<br /> LibIFace = IExec-&gt;GetInterface(LibBase, &quot;main&quot;, ifaceversion, NULL);<br /> if(LibIFace == NULL)<br /> {<br /> // Could not get Interface, so exit.<br /> }<br /> else<br /> {<br /> // Interface obtained, so use its functions.<br /> }<br /> }<br /> }<br /> &lt;/syntaxhighlight&gt;<br /> <br /> ; LibBase<br /> : This is a pointer to the library structure in memory, often referred to as the ''library base''. The library may or may not be global depending on your needs. The name of this pointer may be changed although it is proper to use the established standard name. Refer to the list below for the appropriate name.<br /> <br /> ; LibIFace<br /> : This is a pointer to the interface structure in memory. The interface may or may not be global depending on your needs. The name of this pointer may be changed although it is proper to use the established standard name. Refer to the list below for the appropriate name.<br /> <br /> ; library.name<br /> : This is a C string that describes the name of the library you wish to open. The list of Amiga library names is given below.<br /> <br /> ; main<br /> : This is a C string that describes the name of the interface you wish to use. The list of Amiga interface names depends on the library and is given below.<br /> <br /> ; libversion<br /> : This should be set to the earliest acceptable library version. A value of 0 matches any version. A value of 53 means you require at least version 53 or a later version of the library. If the library version in the system is older than the one you specify, OpenLibrary() will fail (return 0).<br /> <br /> ; ifaceversion<br /> : This should be set to the interface version you require. Each interface has a unique version number which defines all the functions in that interface. Most often an interface will have a single interface version of 1. If the interface version in the system does not match, GetInterface() will fail (return 0).<br /> <br /> The table listed below shows all the function libraries that are currently part of the Amiga system software.<br /> <br /> {| class=&quot;wikitable&quot;<br /> |+ Parameters to use with OpenLibrary()<br /> !Library Name<br /> !Library Base<br /> !Oldest Library Version In Use<br /> !Interface Name:Version<br /> |-<br /> | library.name&lt;sup&gt;*&lt;/sup&gt; || LibBase || version || iface.name:version<br /> |-<br /> | asl.library || AslBase || 50 || main:1<br /> |-<br /> | commodities.library || CxBase || 50 || main:1<br /> |-<br /> | diskfont.library || DiskfontBase || 50 || main:1<br /> |-<br /> | dos.library || DOSBase || 50 || main:1<br /> |-<br /> | [[Introduction to Exec|exec.library]] || ExecBase || 50 || main:1<br /> |-<br /> | [[Expansion Library|expansion.library]] || ExpansionBase || 50 || main:1<br /> |-<br /> | gadtools.library || GadToolsBase || 50 || main:1<br /> |-<br /> | graphics.library || GfxBase || 50 || main:1<br /> |-<br /> | icon.library || IconBase || 50 || main:1<br /> |-<br /> | iffparse.library || IFFParseBase || 50 || main:1<br /> |-<br /> | intuition.library || IntuitionBase || 50 || main:1<br /> |-<br /> | keymap.library || KeymapBase || 50 || main:1<br /> |-<br /> | layers.library || LayersBase || 50 || main:1<br /> |-<br /> | mathffp.library || MathBase || 50 || main:1<br /> |-<br /> | mathtrans.library || MathTransBase || 50 || main:1<br /> |-<br /> | mathieeedoubbas.library || MathIeeeDoubBasBase || 50 || main:1<br /> |-<br /> | mathieeedoubtrans.library || MathIeeeDoubTransBase || 50 || main:1<br /> |-<br /> | mathieeesingbas.library || MathIeeeSingBasBase || 50 || main:1<br /> |-<br /> | mathieeesingtrans.library || MathIeeeSingTransBase || 50 || main:1<br /> |-<br /> | rexxsyslib.library || RexxSysBase || 50 || main:1<br /> |-<br /> | translator.library || TranslatorBase || 50 || main:1<br /> |-<br /> | [[Utility Library|utility.library]] || UtilityBase || 50 || main:1<br /> |-<br /> | workbench.library || WorkbenchBase || 50 || main:1<br /> |}<br /> <br /> &lt;sup&gt;*&lt;/sup&gt; Other libraries may exist that are not supplied by the AmigaOS development team since it is a feature of the operating system to allow such libraries.<br /> <br /> ==== Opening a Library in C ====<br /> <br /> Here's a brief example showing how OpenLibrary() and GetInterface() are used in C.<br /> <br /> &lt;syntaxhighlight&gt;<br /> /* easy.c: a complete example of how to open an Amiga function library in C.<br /> * In this case the function library is Intuition. Once the Intuition<br /> * function library is open and the interface obtains, any Intuition function<br /> * can be called. This example uses the DisplayBeep() function of Intuition to<br /> * flash the screen.<br /> */<br /> <br /> #include &lt;proto/exec.h&gt;<br /> #include &lt;proto/intuition.h&gt;<br /> <br /> struct Library *IntuitionBase;<br /> struct IntuitionIFace *IIntuition;<br /> <br /> int main()<br /> {<br /> IntuitionBase = IExec-&gt;OpenLibrary(&quot;intuition.library&quot;, 50);<br /> <br /> // Note it is safe to call GetInterface() with a NULL library pointer.<br /> IIntuition = (struct IntuitionIFace *)IExec-&gt;GetInterface(IntuitionBase, &quot;main&quot;, 1, NULL);<br /> <br /> if(IIntuition != NULL) /* Check to see if it actually opened. */<br /> { /* The Intuition library is now open so */<br /> IIntuition-&gt;DisplayBeep(0); /* any of its functions may be used. */<br /> }<br /> <br /> // Always drop the interface and close the library if not in use.<br /> // Note it is safe to call DropInterface() and CloseLibrary() with NULL pointers.<br /> IExec-&gt;DropInterface((struct Interface *)IIntuition);<br /> IExec-&gt;CloseLibrary(IntuitionBase);<br /> }<br /> &lt;/syntaxhighlight&gt;<br /> <br /> ==== Another Kind of Function Library ====<br /> <br /> The Amiga has two kinds of libraries: run-time libraries and link libraries. All the libraries discussed so far are run-time libraries. Run-time libraries make up most of the Amiga's operating system and are the main topic of this book.<br /> <br /> There is another type of library known as a link library. Even though a link library is a collection of functions just like a run-time library, there are some major differences in the two types.<br /> <br /> A run-time, or shared library is a group of functions managed by [[Exec]] that resides either in ROM or on disk (in the &quot;LIBS:&quot; directory). A run-time library must be opened before it can be used (as explained above). The functions in a run-time library are accessed dynamically at run-time and can be used by many programs at once even though only one copy of the library is in memory. A disk based run-time library is loaded into memory only if requested by a program and can be automatically flushed from memory when no longer needed.<br /> <br /> A link library is a group of functions on disk that are managed by the compiler at link time. Link libraries do not have to be opened before they are used, instead you must link your code with the library when you compile a program. The functions in a link library are actually copied into every program that uses them. For instance the exit() function used in the C program listed above is not part of any of the libraries that make up the Amiga OS. It comes from the link library supplied with the compiler. The code that performs the exit() function is copied into the program when it is compiled.<br /> <br /> ==== Libraries, Devices and Resources ====<br /> <br /> Most of the Amiga's OS routines are organized into groups of shared run-time libraries. The Amiga also has specialized function groups called ''devices'' and ''resources'' that programmers use to perform basic I/O operations or access low-level hardware.<br /> <br /> Devices and resources are similar in concept to a shared run-time library. They are managed by [[Exec]] and must be opened before they can be used. Their functions are separate from the programs that use them and are accessed dynamically at run time. Multiple programs can access the device or resource even though only one copy exists in memory (a few resources can only be used by one program at a time.)<br /> <br /> [[File:LibFig1-1a.png|frame|center|'''Figure 1-1: Amiga System Software Hierarchy''']]<br /> <br /> &lt;center&gt;&lt;/center&gt;<br /> <br /> Devices and resources are managed by [[Exec]] just as libraries are. For more information on devices and resources, see the respective sections.<br /> <br /> {{Note|title=What Every Amiga Programmer Should Know|text=The functions in the Amiga OS are accessed through shared run-time libraries. Libraries must be opened before their functions may be used. The system's master library, [[Exec]], is always open. The [[Exec]] function OpenLibrary() is used to open all other libraries.}}<br /> <br /> === Dynamic memory architecture ===<br /> <br /> Unlike some microcomputer operating systems, the AmigaOS relies on absolute memory addresses as little as possible. Instead the Amiga OS uses a technique (sometimes referred to as soft machine architecture) which allows system routines and data structures to be positioned anywhere in memory.<br /> <br /> Amiga run-time libraries may be positioned anywhere in memory because they are always accessed through a jump table. Each library whether in ROM or loaded from disk has an associated Library structure and jump table in RAM.<br /> <br /> [[File:LibFig1-1b.png|frame|center|Amiga Library Structure and Jump Table]]<br /> <br /> The system knows where the jump table starts in RAM because when a library is opened for the first time, [[Exec]] creates the library structure and keeps track of its location. The order of the entries in the library's jump table is always preserved between versions of the OS but the functions they point to can be anywhere in memory. Hence, system routines in ROM may be moved from one version of the OS to another. Given the location of the jump table and the appropriate offset into the table, any function can always be found.<br /> <br /> Not only are system routines relocatable but system data structures are too. In the Amiga's multitasking environment, multiple applications run at the same time and each may have its own screen, memory, open files, and even its own subtasks. Since any number of application tasks are run and stopped at the user's option, system data structures have to be set up as needed. They cannot be set up ahead of time at a fixed memory location because there is no way to tell how many and what type will be needed.<br /> <br /> The Amiga system software manages this confusion by using ''linked lists'' of information about items such as libraries, tasks, screens, files and available memory. A linked list is a chain of data items with each data item containing a pointer to the next item in the chain. Given a pointer to the first item in a linked list, pointers to all the other items in the chain can be found.<br /> <br /> ==== Exec: The System Executive ====<br /> <br /> On the Amiga, the module that keeps track of linked lists is [[Exec]], the system executive. [[Exec]] is the heart of the Amiga operating system since it also is in charge of multitasking, granting access to system resources (like memory) and managing the Amiga library system.<br /> <br /> As previously discussed, memory location 4 ($0000 0004), also known as SysBase, contains a pointer to the [[Exec]] library structure. This is the only absolutely defined location in the Amiga operating system. A program need only know where to find the [[Exec]] library to find, use and manipulate all other system code and data.<br /> <br /> [[File:LibFig1-2.png|frame|center|[[Exec]] and the Organization of the Amiga OS]]<br /> <br /> The diagram above shows how the entire Amiga operating system is built as a tree starting at SysBase. [[Exec]] keeps linked lists of all the system libraries, devices, memory, tasks and other data structures. Each of these in turn can have its own variables and linked lists of data structures built onto it. In this way, the flexibility of the OS is preserved so that upgrades can be made without jeopardizing compatibility.<br /> <br /> {{Note|title=What Every Amiga Programmer Should Know|text=The Amiga has a dynamic memory map. There are no fixed locations for operating system variables and routines. Do not call ROM routines or access system data structures directly. Instead use the indirect access methods provided by the system.}}<br /> <br /> === Operating system versions ===<br /> <br /> The Amiga operating system has undergone several major revisions. The latest revision is Release 4.1 (corresponds to library version 53).<br /> <br /> See the table in the [[Introduction_to_Exec#Libraries_and_Devices|Libraries and Devices]] section for details on which version corresponds to which OS release.<br /> <br /> The examples listed throughout this wiki assume you are using Release 4.0 or higher.<br /> <br /> Many of the libraries and functions documented in this manual are available in all versions of the Amiga operating system. Others are completely new and cannot be used unless you have successfully opened the appropriate version of the library.<br /> <br /> To find out which functions are new, refer to the SDK. The functions which are new are marked with ''(V50)'' or ''(V51)'' in the NAME line of the function Autodoc. These new functions require you to use the corresponding version number (50, 51, or higher) when opening the library.<br /> <br /> Exit gracefully and informatively if the required library version is not available.<br /> <br /> ==== About Release 4 ====<br /> <br /> Release 4 first appeared on the ''AmigaOne XE''. This initial version corresponds to Kickstart 4.0, system library version number V50.<br /> <br /> {{Note|title=What Every Amiga Programmer Should Know|text=Some libraries or specific functions are not available in older versions of the Amiga operating system. Be sure to ask for the lowest library version that meets the requirements of your program.}}<br /> <br /> ==== Two Kinds of Memory ====<br /> <br /> To keep the Classic Amiga running efficiently, the Classic Amiga has two memory buses and two kinds of memory. ''Chip memory'' is memory that both the CPU and custom chips can access. ''Fast memory'' is memory that only the CPU (and certain expansion cards) can access. Since Chip memory is shared, CPU access may be slowed down if the custom chips are doing heavy-duty processing. CPU access to Fast memory is never slowed down by contention with the custom chips.<br /> <br /> The distinction between Chip memory and Fast memory is very important for Classic Amiga programmers to keep in mind because any data accessed directly by the custom chips such as video display data, audio data or sprite data ''must be in Chip memory''.<br /> <br /> {| class=&quot;wikitable&quot;<br /> | ''What Every Amiga Programmer Should Know'': The Classic Amiga has ''two'' kinds of memory: ''Chip'' memory and ''Fast'' memory. Use the right kind.<br /> |}<br /> <br /> '''NOTE'''<br /> There is no such thing as ''Chip'' memory in any of new PowerPC-based Amiga systems. The two types of memory only applies to the Classic Amiga hardware platforms such as the A1200 and A4000 models.<br /> <br /> == About the Examples ==<br /> <br /> For the most part, the examples in this book are written in C.<br /> <br /> C examples have been compiled using the standard Software Development Kit (SDK) using GCC.<br /> <br /> In general, the examples are also compatible with vbcc and other C compilers, however some changes will usually be necessary.<br /> <br /> Specifically, all the C examples assume that the automatic Ctrl-C feature of the compiler has been disabled. For SAS C (and Lattice C revisions 4.0 and greater) this is handled with:<br /> <br /> &lt;pre&gt;<br /> /* Add this before main() to override the default Ctrl-C handling<br /> * provided in SAS (Lattice) C. Ctrl-C event will be ignored */<br /> <br /> int CXBRK ( void ) { return(0); }<br /> int chkabort( void ) { return(0); }<br /> &lt;/pre&gt;<br /> <br /> Other changes may be required depending on the example and the C compiler you are using. Most of the C examples do not require any special options and rely on the defaults provided by the SDK.<br /> <br /> Except where noted, each example was linked with the standard newlib startup code which provides the following interfaces: IExec, IDOS and IUtility.<br /> <br /> == General Amiga Development Guidelines ==<br /> <br /> This sections presents specific guidelines that all Amiga programmers must follow. Some of these guidelines are for advanced programmers.<br /> <br /> * Check for memory loss. Arrange your Workbench screen so that you have a Shell available and can start your program without rearranging any windows. In the Shell window type Avail flush several times (the flush option requires the Release 2 version of the Avail command). Note the total amount of free memory. Run your program (do not rearrange any windows other than those created by the program) and then exit. At the Shell, type Avail flush several times again. Compare the total amount of free memory with the earlier figure. They should be the same. Any difference indicates that your application is not freeing some memory it used or is not closing a disk-loaded library, device or font it opened. Note that under Release 2, a small amount of memory loss is normal if your application is the first to use the audio or narrator device.<br /> <br /> * Use all of the program debugging and stress tools that are available when writing and testing your code. New debugging tools such as Enforcer, MungWall, and Scratch can help find uninitialized pointers, attempted use of freed memory and misuse of scratch registers or condition codes (even in programs that appear to work perfectly).<br /> <br /> * Always make sure you actually get any system resource that you ask for. This applies to memory, windows, screens, file handles, libraries, devices, ports, etc. Where an error value or return is possible, ensure that there is a reasonable failure path. Many poorly written programs will appear to be reliable, until some error condition (such as memory full or a disk problem) causes the program to continue with an invalid or null pointer, or branch to untested error handling code.<br /> <br /> * Always clean up after yourself. This applies for both normal program exit and program termination due to error conditions. Anything that was opened must be closed, anything allocated must be deallocated. It is generally correct to do closes and deallocations in reverse order of the opens and allocations. Be sure to check your development language manual and startup code; some items may be closed or deallocated automatically for you, especially in abort conditions. If you write in the C language, make sure your code handles Ctrl-C properly.<br /> <br /> * Remember that memory, peripheral configurations, and ROMs differ between models and between individual systems. Do not make assumptions about memory address ranges, storage device names, or the locations of system structures or code. Never call ROM routines directly. Beware of any example code you find that calls routines at addresses in the $F00000 $FFFFFF range. These are ROM routines and they will move with every OS release. The only supported interface to system ROM code is through the library, device, and resource calls.<br /> <br /> * Never assume library bases or structures will exist at any particular memory location. The only absolute address in the system is $00000004, which contains a pointer to the Exec library base. Do not modify or depend on the format of private system structures. This includes the poking of copper lists, memory lists, and library bases.<br /> <br /> * Never assume that programs can access hardware resources directly. Most hardware is controlled by system software that will not respond well to interference from other programs. Shared hardware requires programs to use the proper sharing protocols. Use the defined interface; it is the best way to ensure that your software will continue to operate on future models of the Amiga.<br /> <br /> * Never access shared data structures directly without the proper mutual exclusion (locking). Remember that other tasks may be accessing the same structures.<br /> <br /> * The system does not monitor the size of a program‚Äôs stack. (Your compiler may have an option to do this for you.) Take care that your program does not cause stack overflow and provide extra stack space for the possibility that some functions may use up additional stack space in future versions of the OS.<br /> <br /> * Never use a polling loop to test signal bits. If your program waits for external events like menu selection or keystrokes, do not bog down the multitasking system by busy-waiting in a loop. Instead, let your task go to sleep by ''Wait()''ing on its signal bits. For example:<br /> signals = (ULONG)Wait( (1&amp;lt;&amp;lt;windowPtr-&amp;gt;UserPort-&amp;gt;mp_SigBit) |<br /> (1&amp;lt;&amp;lt;consoleMsgPortPtr-&amp;gt;mp_SigBit) );<br /> <br /> * This turns the signal bit number for each port into a mask, then combines them as the argument for the Exec library Wait() function. When your task wakes up, handle all of the messages at each port where the mp_SigBit is set. There may be more than one message per port, or no messages at the port. Make sure that you ReplyMsg() to all messages that are not replies themselves. If you have no signal bits to Wait() on, use Delay() or WaitTOF() to provide a measured delay.<br /> <br /> * Tasks (and processes) execute in ''680x0'' user mode. Supervisor mode is reserved for interrupts, traps, and task dispatching. Take extreme care if your code executes in supervisor mode. Exceptions while in supervisor mode are deadly.<br /> <br /> * Most system functions require a particular execution environment. All DOS functions and any functions that might call DOS (such as the opening of a disk-resident library, font, or device) can only be executed from a process. A task is not sufficient. Most other kernel functions may be executed from tasks. Only a few may be executed from interrupts.<br /> <br /> * Never disable interrupts or multitasking for long periods. If you use Forbid() or Disable(), you should be aware that execution of any system function that performs the Wait() function will temporarily suspend the Forbid() or Disable() state, and allow multitasking and interrupts to occur. Such functions include almost all forms of DOS and device I/O, including common ''stdio'' functions like printf().<br /> <br /> * Never tie up system resources unless it is absolutely necessary. For example, if your program does not require constant use of the printer, open the printer device only when you need it. This will allow other tasks to use the printer while your program is running. You must provide a reasonable error response if a resource is not available when you need it.<br /> <br /> * All data for the custom chips must reside in Chip memory (type MEMF_CHIP). This includes bitplanes, sound samples, trackdisk buffers, and images for sprites, bobs, pointers, and gadgets. The AllocMem() call takes a flag for specifying the type of memory. A program that specifies the wrong type of memory may appear to run correctly because many Amigas have only Chip memory. (On all models of the Amiga, the first 512K of memory is Chip memory. In later models, Chip memory may occupy up to the first one or two megabytes).<br /> <br /> * However, once expansion memory has been added to an Amiga (type MEMF_FAST), any memory allocations will be made in the expansion memory area by default. Hence, a program can run correctly on an unexpanded Amiga which has only Chip memory while crashing on an Amiga which has expanded memory. A developer with only Chip memory may fail to notice that memory was incorrectly specified.<br /> <br /> * Most compilers have options to mark specific data structures or object modules so that they will load into Chip RAM. Some older compilers provide the Atom utility for marking object modules. If this method is unacceptable, use the AllocMem() call to dynamically allocate Chip memory, and copy your data there.<br /> <br /> * When making allocations that do not require Chip memory, do not explicitly ask for Fast memory. Instead ask for memory type MEMF_PUBLIC or 0L as appropriate. If Fast memory is available, you will get it.<br /> <br /> * Never use software delay loops! Under the multitasking operating system, the time spent in a loop can be better used by other tasks. Even ignoring the effect it has on multitasking, timing loops are inaccurate and will wait different amounts of time depending on the specific model of Amiga computer. The timer device provides precision timing for use under the multitasking system and it works the same on all models of the Amiga. The AmigaDOS Delay() function or the graphics library WaitTOF() function provide a simple interface for longer delays. The ''8520'' I/O chips provide timers for developers who are bypassing the operating system (see the ''Amiga Hardware Reference Manual'' for more information).<br /> <br /> Always obey structure conventions!<br /> <br /> * All non-byte fields must be word-aligned. Longwords should be longword-aligned for performance.<br /> <br /> * All address pointers should be 32 bits (not 24 bits). Never use the upper byte for data.<br /> <br /> * Fields that are not defined to contain particular initial values must be initialized to zero. This includes pointer fields.<br /> <br /> * All reserved or unused fields must be initialized to zero for future compatibility.<br /> <br /> * Data structures to be accessed by the custom chips, public data structures (such as a task control block), and structures which must be longword aligned must '''not''' be allocated on a program's stack.<br /> <br /> * Dynamic allocation of structures with AllocMem() provides longword aligned memory of a specified type with optional initialization to zero, which is useful in the allocation of structures.<br /> <br /> === Hardware programming guidelines ===<br /> <br /> If you find it necessary to program the hardware directly, then it is your responsibility to write code that will work correctly on the various models and configurations of the Amiga. Be sure to properly request and gain control of the hardware resources you are manipulating, and be especially careful in the following areas:<br /> <br /> * Kickstart 2.0 uses the ''8520'' Complex Interface Adaptor (CIA) chips differently than 1.3 did. To ensure compatibility, you must always ask for CIA access using the cia.resource AddICRVector() and RemICRVector() functions. Do not make assumptions about what the system might be using the CIA chips for. If you write directly to the CIA chip registers, do not expect system services such as the trackdisk device to function. If you are leaving the system up, do not read or write to the CIA Interrupt Control Registers directly; use the cia.resource AbleICR(), and SetICR() functions. Even if you are taking over the machine, do not assume the initial contents of any of the CIA registers or the state of any enabled interrupts.<br /> <br /> * All custom chip registers are Read-only or Write-only. Do not read Write-only registers, and do not write to Read-only registers.<br /> <br /> * Never write data to, or interpret data from the unused bits or addresses in the custom chip space. To be software-compatible with future chip revisions, all undefined bits must be set to zeros on writes, and must be masked out on reads before interpreting the contents of the register.<br /> <br /> * Never write past the current end of custom chip space. Custom chips may be extended or enhanced to provide additional registers, or to use bits that are currently undefined in existing registers.<br /> <br /> * Never read, write, or use any currently undefined address ranges or registers. The current and future usage of such areas is reserved by the AmigaOS development team and is subject to change.<br /> <br /> * Never assume that a hardware register will be initialized to any particular value. Different versions of the OS may leave registers set to different values. Check the ''Amiga Hardware Reference Manual'' to ensure that you are setting up all the registers that affect your code.<br /> <br /> === AmigaOS Interface Style Guide ===<br /> <br /> In order to make all programs in AmigaOS look consistent, AmigaOS provides some default thumbnails that developers must use in their GUI. These pictures are located in the '''tbimages:''' assign. They are installed in any AmigaOS installation.<br /> Note that something may still go wrong and these pictures may not be found. In this case, the program must provide a fallback method instead of just failing. The developer can choose to display text-only toolbars or include default pictures with their program.<br /> <br /> While the look of windows and gadgets can be changed by the user, the default look is similar to this: <br /> <br /> [[File:About.png]]<br /> <br /> == Error Reports ==<br /> <br /> All corrections and bug report should be made by posting a new topic at AmigaOS' support forum. The support forum is located at http://support.amigaos.net</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=AmiDock_and_Dockies&diff=6277 AmiDock and Dockies 2013-08-03T18:04:46Z <p>Philippe Ferrucci: </p> <hr /> <div>= Introduction =<br /> <br /> = What is Dock and a Docky =<br /> <br /> == Dock ==<br /> A Dock is an area/a window (currently provided by the &quot;AmiDock&quot; commodity) where the user can put some icons and other stuff. Some may call it &quot;Panels&quot;. <br /> <br /> <br /> So, Docks can be used as Launcher Panels:<br /> <br /> <br /> [[File:Laucher_dock.png|center]]<br /> <br /> <br /> And as Tray Bar panels:<br /> <br /> [[File:Tray_doc.jpg|center]]<br /> <br /> <br /> As anything else anyone can come up with: you can put everything inside of panels of any size, structure and design it as you wish.<br /> <br /> == Docky ==<br /> <br /> In general, A Docky is what you place in the Dock. Dockies are able to control most of AmiDocks feature and provide a great way to expand AmiDocks features beyond its default features. Dockies may be invisible to the user or show static or dynamic (animated) ontent. The may change their behavior, size and look acoring their current equirements. Dockies can be of 2 main types:<br /> <br /> '''Standalone Dockies'''.<br /> <br /> Is a special type of program which is made to show an icon in a Dock, delivering some functionality to the user. It is the most common form of Dockies. This docky-type uses the shared library feature of AmigaOS4 as common interface to the internal properties and behavioral possibilities of a docky.<br /> <br /> '''Application Dockies'''.<br /> <br /> That second type of dockies are application dockies (short form 'AppDockies' or as some call it 'AppDockIcon Dockies'). An AppDocky is a docky which is introduced to the system during runtime by an application using application.librarries registration mechanism for applications. The biggest diference between the two docky types is that AppDockies belong to a running application and usually are used to represent the current state of the owning application.<br /> <br /> To sum up in &quot;standalone dockies&quot; the docky itself is the application (the only reason of existence of the application is the docky) while for &quot;AppDockIcon dockies&quot; the docky is just a graphical representation of a bigger application (the docky is just here to add user friendliness or visual feedback of the surrounding application)<br /> <br /> = What is AmiDock =<br /> <br /> AmiDock is a toolbar system. <br /> <br /> == Dockies provided with AmigaOS4 ==<br /> <br /> === Access.docky ===<br /> <br /> Single click with the left mouse button on this docky to open a list of screens and windows. Select a window and it will be activated and come to front (optionally). This docky especially is cool when using a hotkey - this way you can use the popup on EVERY screen. Just specify the hotkey like you do it with normal icons, too. Use the context menu to toggle to-front mode<br /> <br /> === Anim.docky ===<br /> <br /> On a empty Anim.docky (no Animation assigned yet), drop a GIF-Animation (e.g. Boing#?.gif) on this dockie to change the current animation(in a selected dock) point with the mouse pointer over the docky and press the &quot;+&quot;/&quot;-&quot;-Keys to change animation speed. Use the context menu to specify a tool which shall be combined with this docky. You can also change the used animation here.<br /> <br /> === Button.docky ===<br /> <br /> On a empty Button.docky (no Picture assigned yet), drop a picture on this docky to change the current image. Use the context menu to specify a tool which shall be combined with this docky. You can also change the used picture here.<br /> <br /> === Clock.docky ===<br /> <br /> A analog clock in the dock. This docky changes automatically to a digital clock if you change to name or button style docks. Double click the docky or use the context menu to open the system time preferences.<br /> <br /> === Debugger.docky ===<br /> <br /> This docky opens a window and shows debugging information for docky-programmers. Needed only for people developing third-party dockies. Single-click it to enable/disable debug mode. Debugger.docky saves its state in its preferences. Use the context menu to toggle between single-dock and global (all docks) debugging.<br /> <br /> === Lens.docky ===<br /> <br /> Double click this docky to switch between normal or maximized view<br /> <br /> Note: Normal and maximized view do have their own settings. Do that in a selected dock:<br /> <br /> point with the mouse pointer over the docky and press the key &quot;x&quot; - this will toggle between &quot;cross-hair&quot; mode and non-cross-hair mode.<br /> point with the mouse pointer over the docky and press the &quot;+&quot;/&quot;-&quot;-Keys to change the used magnification<br /> point with the mouse pointer over the docky and press the key &quot;c&quot; to enable coordinates<br /> point with the mouse pointer over the docky and press the key &quot;v&quot; to enable RGB values output (only available in a maximized lens!!)<br /> point with the mouse pointer over the docky and press the key &quot;g&quot; to enable/disable the grid.<br /> <br /> You can also use the context menu to change all the above described settings.<br /> <br /> === Minimizer.docky ===<br /> <br /> As soon as this docky was added to a dock (to make the docky &quot;invisible&quot; use another category for placing the docky), the dock will shrink to the minimized state after some time. As soon as the pointer is placed over the drag-bar, it expands to normal size. You can change the delay time until this docky minimizes the dock using the contextual menu.<br /> <br /> === Online.docky ===<br /> <br /> Allows you to go on- and offline with RoadShow. Not fully implemented yet!!!<br /> <br /> === Rainbow.docky ===<br /> <br /> This docky shows a colorful rainbow with alpha channel (!) - but nothing more. Double click it to toggle between icon and image view. This dock needs screen depth &gt;8Bit. AmiDock will deny it on screen depths below 8Bit.<br /> <br /> === Seperator.docky ===<br /> <br /> This docky is nothing more than just a seperator line. It automatically adjusts itself to the size and orientation of a dock.<br /> <br /> === SubDocks.docky ===<br /> <br /> Use the shortcut Amiga+U to place it in the current dock or throw it in the dock which shall contain it...<br /> <br /> - drag&amp;drop a icon on it to configure its icon in AmiDock<br /> - if you delete the subdock, the docky will remove itself automatically<br /> - if you delete the docky, the docky will remove the subdock itself automatically<br /> - (in a selected dock) point with the mouse pointer over the docky and press the key &quot;p&quot; to toggle between popupmode (default, closes the dock after a object was clicked) or normal mode (doesn't close the dock)<br /> - Use the context menu to toggle the popup mode and ti change the icon.<br /> <br /> === Test.docky ===<br /> The first docky ever written. Just a fun-docky. This docky &quot;listens&quot; to all possible events and shows this by flashing in some color when a action is detected. Move your mouse over the docky and click it. Drag&amp;Drop several files on the docky and watch what happens. This dock needs screen depth &gt;8Bit. AmiDock will deny it on screen depths below 8Bit.<br /> <br /> == AmiDock's hints ==<br /> <br /> - If the Minimizeable-Checkbox is checked, you can minimize a dock by double-clicking it's drag-bar.<br /> <br /> - Bring to front/send to back can be done by double clicking on an empty area in a dock (SHIFT together with a dobule click will send it to back).<br /> <br /> - in a selected dock: shift+click+hold on a icon and move around to interactively change the icon-position<br /> <br /> - to interactively delete a icon or a whole dock: click+hold the object, press the Backspace or Delete key<br /> <br /> = AmiDock's API =<br /> <br /> = Different types of Dockies =<br /> == Standalone Dockies ==<br /> <br /> == AppDockIcon Dockies ==<br /> <br /> = How to make a right Docky =<br /> <br /> = How to make a Docky for tray-bar kind Docks =<br /> <br /> If you as developer want to make your dockies to work in tray-bar kind docks, you need to make a docky more flexible, and you should follow some rulz when you do it:<br /> <br /> 1. <br /> <br /> 2.<br /> <br /> 3.<br /> <br /> <br /> = FAQ =<br /> <br /> = Final Words =<br /> <br /> = Links =<br /> <br /> 1. SDK:Documentation/AutoDocs/docky.doc<br /> <br /> 2. Sys:Documentation/Commodities/AmiDock_Arexx.doc</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=AmiDock_and_Dockies&diff=6267 AmiDock and Dockies 2013-08-03T10:19:34Z <p>Philippe Ferrucci: </p> <hr /> <div>= Introduction =<br /> <br /> = What is AmiDock =<br /> <br /> = What is Dock and Dockie =<br /> <br /> == Dock ==<br /> A Dock is an area/a window (currently provided by the &quot;AmiDock&quot; commodity) where the user can put some icons and other stuff. Some may call it &quot;Panels&quot;.<br /> <br /> == Dockie ==<br /> <br /> A Dockie cat be of 3 types:<br /> <br /> 1. &quot;Standalone Dockies&quot;: is a special type of program which is made to show an icon in a Dock, delivering some functionality to the user.<br /> 2. &quot;Standard AppDockIcon Dockies&quot; which is a modern incarnation of AppIcon of some kind.<br /> 3. &quot;Tray-bar AppDockIcon Dockies&quot; which is special case of AppDockIcon Dockies, just done in mind to be in &quot;tray&quot;.<br /> <br /> To sum up in &quot;standalone dockies&quot; the docky itself is the application (the only reason of existence of the application is the docky) while for &quot;AppDockIcon dockies&quot; the docky is just a graphical representation of a bigger application (the docky is just here to add user friendliness or visual feedback of the surrounding application)<br /> <br /> = AmiDock's API =<br /> <br /> = Different types of Dockies =<br /> == Standalone Dockies ==<br /> <br /> == AppDockIcon Dockies ==<br /> === Standard AppDockIcon Dockies ===<br /> === Tray-bar AppDockIcon Dockies ===<br /> <br /> - This part is under development, and even no standard is done. All of this subject to change and just a first attempts -<br /> <br /> [[File:Tray_doc.jpg|center]]<br /> <br /> If you as developer want to make a tray-bar kind dockie, then you should follow some rules:<br /> <br /> 1. You always should provide a 24x24 icon (which can be as standard size of the tray-bar icons). You should do so to avoid auto-scaling of tray-kind doc and make it look as intended.<br /> <br /> 2.<br /> <br /> 3.<br /> <br /> = How to make a good Dockie =<br /> <br /> = FAQ =<br /> <br /> = Final Words =<br /> <br /> = Links =<br /> <br /> 1. Sys:Documentation/Commodities/AmiDock_Arexx.doc<br /> <br /> = Misc =<br /> <br /> <br /> <br /> *******************************************<br /> ***** Welcome to AmiDock *****<br /> ***** for AmigaOS 4 *****<br /> *******************************************<br /> <br /> This Archive contains a beta version of AmiDock.<br /> Please refer to the amidock_relnotes for more information<br /> about the internal changes.<br /> <br /> ---<br /> <br /> The usage of AmiDock should be self-explanory.<br /> Some important things:<br /> <br /> - The &quot;Dockies&quot;-drawer should be located in &quot;Sys:Tools/&quot;<br /> <br /> - If the Minimizeable-Checkbox is checked, you can minimize a dock<br /> by double-clicking it's drag-bar.<br /> <br /> - Bring to front/send to back can be done by double clicking on an<br /> empty area in a dock (SHIFT together with a dobule click will send<br /> it to back).<br /> <br /> - (in a selected dock) shift+click+hold on a icon and move around to<br /> interactively change the icon-position<br /> <br /> - to interactively delete a icon or a whole dock: click+hold the object,<br /> press the Backspace or Delete key<br /> <br /> <br /> Docky-Descriptions:<br /> <br /> <br /> ************* Access.docky ****************************************************<br /> <br /> - Single click with the left mouse button on this docky to open a list of<br /> screens and windows. Select a window and it will be activated and<br /> come to front (optionally)<br /> <br /> - This docky especially is cool when using a hotkey - this way you can use<br /> the popup on EVERY screen. Just specify the hotkey like you do it with<br /> normal icons, too.<br /> <br /> - Use the context menu to toggle to-front mode<br /> <br /> ************* Anim.docky ******************************************************<br /> <br /> - On a empty Anim.docky (no Animation assigned yet), drop a GIF-Animation<br /> (e.g. Boing#?.gif) on this docky to change the current animation<br /> <br /> - (in a selected dock) point with the mouse pointer over the docky<br /> and press the &quot;+&quot;/&quot;-&quot;-Keys to change animation speed<br /> <br /> - Use the context menu to specify a tool which shall be combined with this<br /> docky. You can also change the used animation here.<br /> <br /> ************* Button.docky ****************************************************<br /> <br /> - On a empty Button.docky (no Picture assigned yet), drop a picture<br /> on this docky to change the current image<br /> <br /> - Use the context menu to specify a tool which shall be combined with this<br /> docky. You can also change the used picture here.<br /> <br /> ************* Clock.docky *****************************************************<br /> <br /> A analog clock in the dock. This docky changes automatically to a digital<br /> clock if you change to name or button style docks.<br /> <br /> - Double click the docky or use the context menu to open the system time<br /> preferences.<br /> <br /> ************* Debugger.docky **************************************************<br /> <br /> This docky opens a window and shows debugging information for docky-<br /> programmers. Needed only for people developing third-party dockies.<br /> Single-click it to enable/disable debug mode. Debugger.docky saves its state<br /> in its preferences.<br /> Use the context menu to toggle between single-dock and global (all docks)<br /> debugging.<br /> <br /> ************* Lens.docky ******************************************************<br /> <br /> - Double click this docky to switch between normal or maximized view<br /> Note: Normal and maximized view do have their own settings.<br /> <br /> - (in a selected dock) point with the mouse pointer over the docky<br /> and press the key &quot;x&quot; - this will toggle between &quot;cross-hair&quot; mode and<br /> non-cross-hair mode<br /> <br /> - (in a selected dock) point with the mouse pointer over the docky<br /> and press the &quot;+&quot;/&quot;-&quot;-Keys to change the used magnifcation<br /> <br /> - (in a selected dock) point with the mouse pointer over the docky<br /> and press the key &quot;c&quot; to enable coordinates<br /> <br /> - (in a selected dock) point with the mouse pointer over the docky<br /> and press the key &quot;v&quot; to enable RGB values output<br /> (only available in a maximized lens!!)<br /> <br /> - (in a selected dock) point with the mouse pointer over the docky<br /> and press the key &quot;g&quot; to enable/disable the grid<br /> <br /> You can also use the context menu to change all the above described settings.<br /> <br /> ************* Minimizer.docky *************************************************<br /> <br /> As soon as this docky was added to a dock (to make the docky &quot;invisible&quot;<br /> use another category for placing the docky), the dock will shrink to the<br /> minimized state after some time.<br /> As soon as the pointer is placed over the drag-bar, it expands to normal size.<br /> You can change the delay time until this docky minimizes the dock using the<br /> contextual menu.<br /> <br /> ************* Online.docky ****************************************************<br /> <br /> Allows you to go on- and offline with RoadShow. Not fully implemented yet!!!<br /> <br /> ************* Rainbow.docky ***************************************************<br /> <br /> This docky shows a colorful rainbow with alpha channel (!) - but nothing more.<br /> Double click it to toggle between icon and image view.<br /> <br /> This dock needs screen depth &gt;8Bit. AmiDock will deny it on screen depths<br /> below 8Bit.<br /> <br /> ************* Seperator.docky *************************************************<br /> <br /> This docky is nothing more than just a seperator line. It automatically<br /> adjusts itself to the size and orientation of a dock.<br /> <br /> ************* SubDocks.docky **************************************************<br /> <br /> - Use the shortcut Amiga+U to place it in the current dock or throw it in the<br /> dock which shall contain it...<br /> <br /> - drag&amp;drop a icon on it to configure its icon in AmiDock<br /> <br /> - if you delete the subdock, the docky will remove itself automatically<br /> <br /> - if you delete the docky, the docky will remove the subdock itself<br /> automatically<br /> <br /> - (in a selected dock) point with the mouse pointer over the docky<br /> and press the key &quot;p&quot; to toggle between popupmode (default, closes the dock<br /> after a object was clicked) or normal mode (doesn't close the dock)<br /> <br /> - Use the context menu to toggle the popup mode and ti change the icon.<br /> <br /> ************* Test.docky ******************************************************<br /> <br /> The first docky ever written. Just a fun-docky.<br /> This docky &quot;listens&quot; to all possible events and shows this by flashing in some<br /> color when a action is detected.<br /> <br /> - Move your mouse over the docky and click it...<br /> <br /> - Drag&amp;Drop several files on the docky and watch what happens...<br /> <br /> This dock needs screen depth &gt;8Bit. AmiDock will deny it on screen depths<br /> below 8Bit.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=UserDoc:How_AmigaOS_Works&diff=6216 UserDoc:How AmigaOS Works 2013-07-29T21:13:39Z <p>Philippe Ferrucci: /* AmigaOS boot procedure */</p> <hr /> <div>As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.<br /> <br /> In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.<br /> <br /> = Introduction: The most important components =<br /> <br /> == Exec, the AmigaOS kernel ==<br /> <br /> Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible of running programs, dealing with computer memory, managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.<br /> <br /> It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.<br /> <br /> == AmigaDOS: the underlying system ==<br /> <br /> The word &quot;DOS&quot; was originally an acronym for &quot;Disk Operating System&quot;. Some say it should be &quot;Disk Based Operating System&quot; as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be &quot;Device Operating System&quot;.<br /> <br /> The whole AmigaDOS system includes things such as:<br /> <br /> * A set of commands that can be used in the Shell window and elsewhere.<br /> * A system for saving data to disk and retrieving it from disk.<br /> * A system for filing data on disks.<br /> * An interface for peripherals such as keyboards, monitors, printers, etc.<br /> * A method of running programs<br /> * A multitasking system for running more than one program at a time.<br /> * etc. etc. etc.<br /> <br /> Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.<br /> <br /> == The Graphics library ==<br /> <br /> The Graphics library handles every low level graphic operations like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.<br /> <br /> == Intuition ==<br /> <br /> The Intuition library is responsible for every graphical objects: windows, screens, gadgets, mouse pointers... It lays between any graphic program and the graphics library.<br /> <br /> == The Workbench ==<br /> <br /> The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.<br /> [[File:Wb.png|320px]]<br /> <br /> == The Shell ==<br /> <br /> While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.<br /> <br /> == ARexx - inter-program communication by scripting ==<br /> <br /> The ARexx scripting language can be used to operate the Workbench and the most important Amiga applications from a script containing ARexx commands. This is extremely useful to perform repetitive tasks or to do what the controlled application was not even design to do.<br /> After a learning curve, everybody can use ARexx as it is built in the system and the scripts can be executed immediately like any other tool.<br /> <br /> = How is my data stored? =<br /> == Files ==<br /> === Executable files ===<br /> Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.<br /> An example is a music player. When you start this executable, the player opens and you can start playing music files.<br /> <br /> AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The laters are executed inside an emulation that transcripts them into PowerPC code.<br /> <br /> ==== Scripts ====<br /> <br /> Scripts are text files containing a list of commands. So they are not strictly executables like ''binary code'' files but they can be executed by AmigaOS like if they were.<br /> This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.<br /> <br /> === Data files ===<br /> Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.<br /> <br /> == Directories/Drawers ==<br /> In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.<br /> Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.<br /> <br /> Note: directories are often called ''folders'' on other systems.<br /> <br /> == Disks, partitions and volumes ==<br /> === Disks ===<br /> Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.<br /> <br /> === Partitions ===<br /> A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.<br /> <br /> [[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]<br /> <br /> On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.<br /> <br /> === Volumes ===<br /> A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.<br /> <br /> = How to identify files/directories =<br /> <br /> == On the Workbench ==<br /> <br /> The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...<br /> <br /> In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.<br /> <br /> == In a shell ==<br /> <br /> In a shell you need to issue the command '''list''' to see if an object is a file or a directory.<br /> <br /> [[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]<br /> <br /> A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.<br /> <br /> Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.<br /> <br /> = All AmigaOS components =<br /> <br /> AmigaOS is made of different components which have their own job in the system. The most important ones are mandatory. Without them the system does not even start. Other components are less important and the user can choose to use them or not. This is the case of drivers. For instance, a device driver may be omitted. If so, the corresponding device will just not work as AmigaOS will have no driver that allows it to know what to do with this device.<br /> <br /> == Kickstart modules ==<br /> <br /> These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is some kind of director handling the work of all other components.<br /> You can find all these modules in the '''Kickstart''' directory in the system volume. Here is a list:<br /> <br /> === Mandatory modules ===<br /> <br /> The following modules are required in any AmigaOS system. Without one of these, the system will not start.<br /> <br /> * kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.<br /> * loader - this component handles the loading of all other kickstart modules<br /> * battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time<br /> * bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS<br /> * bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS<br /> * con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface<br /> * console.device.kmod - it opens a window and reads/writes text to and from that window<br /> * diskboot.kmod - handles the booting of AmigaOS from a supported disk<br /> * diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS<br /> * dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories<br /> * elf.library.kmod - handles the loading of executable programs<br /> * env-handler.kmod - handles the read/writes of environment variables<br /> * FileSystem.resource.kmod - handles the use of the different filesystems<br /> * gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...<br /> * gameport.device.kmod - handles the read/writes of game pads and joysticks<br /> * graphics.library.kmod - collection of functions used to draw graphic elements on the monitor<br /> * hunk.library.kmod - set of functions to read a data stream into memory<br /> * input.device.kmod - handles of input events like keyboard events or mouse clicks<br /> * intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)<br /> * layers.library.kmod - set of functions to be used to handle different layers in graphic operations<br /> * keyboard.device.kmod - driver for the keyboard<br /> * keymap.library.kmod - functions to handle different keymaps<br /> * newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )<br /> * nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage<br /> * nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers<br /> * PCIGraphics.card - driver that supports the use of different graphic cards<br /> * ram-handler.kmod - functions that handles the '''Ram disk:''' special disk<br /> * ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk<br /> * ramlib.kmod - loads disk based libraries and devices for exec.library<br /> * rtg.library - library of functions perform lowlevel graphic operations on graphic cards<br /> * shell.kmod - the AmigaOS command line interface<br /> * strap.kmod - module that handles booting on different disk devices<br /> * timer.device.kmod - driver to give access to timing functions<br /> <br /> === Filesystem support ===<br /> <br /> These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.<br /> <br /> * CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...<br /> * SmartFilesystem - allows to store data on partitions in SFS0 and SFS2<br /> * JXFileSystem - allows to create partitions in JXFS<br /> * FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts<br /> * diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules<br /> <br /> === Hardware drivers ===<br /> <br /> ==== Graphic cards drivers ====<br /> <br /> * 3dfxVoodoo.chip<br /> * 3DLabsPermedia2.chip<br /> * ATIRadeon.chip<br /> * RadeonHD.chip<br /> * siliconmotion502.chip<br /> <br /> ==== Disk drivers ====<br /> <br /> Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.<br /> <br /> * it8212ide.device.kmod<br /> * lsi53c8xx.device.kmod<br /> * sam460sata.device.kmod<br /> * sii3112ide.device.kmod<br /> * sii3512ide.device.kmod<br /> * sii3114ide.device.kmod<br /> * sii0680ide.device.kmod<br /> * sii3132ide.device.kmod<br /> <br /> ==== USB drivers ====<br /> <br /> * hub.usbfd<br /> * usbsys.device<br /> * usbresource.library<br /> * ehci.usbhcd<br /> * ohci.usbhcd<br /> * uhci.usbhcd<br /> * massstorage.usbfd<br /> <br /> ==== Other drivers ====<br /> <br /> * bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded<br /> * bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded<br /> * fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers<br /> * i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers<br /> * xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000<br /> <br /> === Misc modules ===<br /> <br /> * petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor<br /> <br /> == System components ==<br /> <br /> [[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]<br /> <br /> Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.<br /> Here is described a default AmigaOS installation.<br /> <br /> * C<br /> This directory contains AmigaDOS '''C'''ommands<br /> * Classes<br /> contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...<br /> * Devs<br /> contains definition for '''Dev'''ices<br /> * Emulation<br /> contains files used for the 68k emulation (though E-UAE)<br /> * Fonts<br /> contains various systems fonts<br /> * Internet<br /> contains a dialer to connect to Internet<br /> * Kickstart<br /> contains the kickstart modules<br /> * L<br /> contains hand'''l'''ers and filesystems<br /> * Libs<br /> contains dynamic '''Libr'''airies of functions<br /> * Locale<br /> contains all files used to localise the system (catalogs, keymaps...)<br /> * MUI<br /> contains the needed files for programs that use the MUI third party graphic interface<br /> * Prefs<br /> contains the preference programs used to customise AmigaOS<br /> * S<br /> contains the '''S'''cripts<br /> * SObjs<br /> contains .so shared object library files<br /> * Storage<br /> contains other optional files<br /> * System<br /> contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools<br /> * Utilities<br /> contains several utilities<br /> <br /> = Motorola 680x0 Emulators =<br /> <br /> For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.<br /> <br /> In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be &quot;switched off&quot;.<br /> <br /> Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. &quot;Native&quot; PowerPC programs were rare, and every time a PowerPC program called the system, a so called &quot;context switch&quot; occurred between the 680x0 and PowerPC code, often causing a large performance penalty.<br /> <br /> The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor. <br /> <br /> == Two 680x0 Emulators ==<br /> <br /> In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low &quot;reaction time&quot;, and is ideal for time critical parts, such as interrupts.<br /> <br /> The other is Petunia, the &quot;JIT emulator&quot;. A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.<br /> <br /> Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, &quot;on the fly&quot;.<br /> <br /> This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.<br /> <br /> == Features ==<br /> <br /> Emulated opcodes:<br /> * all user and supervisor level opcodes of the Motorola 68040<br /> * all FPU opcodes of the Motorola 68881/68882 <br /> <br /> AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.<br /> <br /> At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.<br /> <br /> == Removing the JIT Emulator ==<br /> <br /> Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.<br /> <br /> If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.<br /> <br /> Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the &quot;Sys:Kickstart/Kicklayout&quot; file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like &quot;DefaultJIT&quot;, or &quot;DefaultNoJIT&quot;.<br /> <br /> == Configuring the Emulators ==<br /> <br /> Petunia cooperates with a so called &quot;black list&quot;. By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.<br /> <br /> If an executable needs to be added to the list, then it can be done by extending the file &quot;DEVS:applications.dos&quot; with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.<br /> <br /> Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.<br /> <br /> Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.<br /> <br /> For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list. <br /> <br /> = AmigaOS boot procedure =<br /> <br /> Basically a computer with AmigaOS does the following when the power button is pushed:<br /> <br /> * [[File:Uboot.jpg|200px]]<br /> the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.<br /> * depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.<br /> * [[File:SLB.png|200px]]<br /> the SLB will analyses all Amiga partitions on the disk it is installed on. It will read each [[UserDoc:kickstart_configuration|system configuration]] it finds on the partitions. It will show all available configurations for the user to select one to load.<br /> The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.<br /> * [[File:Kmods loading.png|200px]]<br /> the SLB loads the kickstart files of the selected configuration and executes the '''Loader''' module<br /> * '''Loader''' executes the kickstart modules (Exec, devices, libraries...)<br /> * AmigaOS becomes alive displaying the AmigaOS boot picture on the monitor<br /> * the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume<br /> * the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.<br /> * the Workbench is started<br /> <br /> At this point the user can use his/her computer.<br /> <br /> = How to make a Bootable USB Memory Stick for AmigaOS 4.1 =<br /> <br /> By Julian Margetson (&quot;Spectre660&quot;)<br /> <br /> Prerequisites:<br /> * USB memory stick of 2 GB or less in size.<br /> * It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.<br /> * Plug the USB memory stick into a USB port on your machine.<br /> * Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.<br /> <br /> Procedure:<br /> # You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.<br /> # Make certain that you have selected usbdisk.device and not any other device.<br /> # Click on &quot;Start&quot;<br /> # You will see the usb mass storage unit connected in a list.<br /> # Make sure that the Unit type displayed for the USB memory stick is &quot;Removable hard disk&quot;<br /> # Select that Unit by clicking on it.<br /> # The first thing that you need to do is to install the RDB onto the USB Memory Stick.<br /> # Click on the &quot;Install&quot; button.<br /> # A window Labeled &quot;RDB/disk geometry editing&quot; comes up.<br /> ## Towards the bottom of the window is the &quot;AmigaOne boot code (SLB)&quot; section.<br /> ## Select the &quot;Install&quot; button .<br /> ## A file requester &quot;Select AmigaOne Boot Code&quot; now comes up with the Drawer choice defaulting to &quot;l:&quot;<br /> ## Select file &quot;slb_v2&quot;. <br /> ## Select Ok.<br /> ## You are now returned to the &quot;RDB/disk geometry editing window&quot;.<br /> ## Select &quot;Ok-accept changes&quot;.<br /> # You are now returned to the display showing the attached USB unit.<br /> # Select &quot;Edit partitions and Filesystems&quot;. You will now see the Window 'Editing partitions for disk&quot;<br /> # Select &quot;Add partition&quot;<br /> # This defaults to using the whole device as a single partition.<br /> # It is possible to use create more partitions but for this tutorial we will only use one.<br /> # You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the &quot;Name&quot; box.<br /> # Now make sure that the Boxes &quot;Automount&quot; and &quot;Bootable&quot; are selected and show the &quot;Tick mark&quot;.<br /> # You need to set &quot;Boot priority&quot; to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the &quot;+&quot; to the right of the &quot;boot priority&quot; box. Normally you can set the boot priority to 2 .<br /> # Next it is time to select the file system to use.<br /> # Select &quot;Select filesystem/edit details&quot;.<br /> # The Window &quot;Editing details for partition 'USB0'&quot; ,or whatever partition name you used, comes up.<br /> ## Select the file system that you are going to use by selecting the pull down menu under &quot;Filesystem chooser&quot;.<br /> ## Only filesystems SFS/00 or SFS/02 will work for a bootable device.<br /> ## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.<br /> ## Next select Blocksize from the &quot;Blocksize&quot; pull down menu. 512 is the correct size to use.<br /> ## Now Select &quot;Ok-accept changes&quot;.<br /> ## Your are now returned to the &quot;Edit partitions for disk&quot; window.<br /> ## Again select &quot;Ok-accept changes&quot;<br /> # You are now returned to the window showing the USB mass storage unit list.<br /> # Select &quot;Save to disk&quot;<br /> # A requester pops up with the options &quot;Yes, Save.&quot; or &quot;No!&quot;<br /> # Select the &quot;Yes, save.&quot; option.<br /> # You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.<br /> # This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.<br /> # Select &quot;Yes, reboot NOW!&quot;.<br /> # Once you have rebooted connect your USB Memory Stick to a USB port.<br /> # A disk icon &quot;USB0:Uninitialized&quot; (or whatever partition name you used) appears on Workbench.<br /> # You now need to format the device.<br /> # To format Select this Icon and go to the Workbench &quot;Icons&quot; menu .<br /> # Select &quot;Format Disk&quot;<br /> # You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.<br /> # You can use either a full Format or a Quick Format. Full Format may take a few minutes.<br /> # Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=UserDoc:How_AmigaOS_Works&diff=6214 UserDoc:How AmigaOS Works 2013-07-29T21:04:12Z <p>Philippe Ferrucci: /* The most important components */</p> <hr /> <div>As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.<br /> <br /> In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.<br /> <br /> = Introduction: The most important components =<br /> <br /> == Exec, the AmigaOS kernel ==<br /> <br /> Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible of running programs, dealing with computer memory, managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.<br /> <br /> It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.<br /> <br /> == AmigaDOS: the underlying system ==<br /> <br /> The word &quot;DOS&quot; was originally an acronym for &quot;Disk Operating System&quot;. Some say it should be &quot;Disk Based Operating System&quot; as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be &quot;Device Operating System&quot;.<br /> <br /> The whole AmigaDOS system includes things such as:<br /> <br /> * A set of commands that can be used in the Shell window and elsewhere.<br /> * A system for saving data to disk and retrieving it from disk.<br /> * A system for filing data on disks.<br /> * An interface for peripherals such as keyboards, monitors, printers, etc.<br /> * A method of running programs<br /> * A multitasking system for running more than one program at a time.<br /> * etc. etc. etc.<br /> <br /> Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.<br /> <br /> == The Graphics library ==<br /> <br /> The Graphics library handles every low level graphic operations like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.<br /> <br /> == Intuition ==<br /> <br /> The Intuition library is responsible for every graphical objects: windows, screens, gadgets, mouse pointers... It lays between any graphic program and the graphics library.<br /> <br /> == The Workbench ==<br /> <br /> The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.<br /> [[File:Wb.png|320px]]<br /> <br /> == The Shell ==<br /> <br /> While some people prefer to control the operating system using their mouse, others prefer using the keyboard. The shell is a text based window when you can type commands to execute actions in the operating system. In the shell the commands will display the results of their execution.<br /> <br /> == ARexx - inter-program communication by scripting ==<br /> <br /> The ARexx scripting language can be used to operate the Workbench and the most important Amiga applications from a script containing ARexx commands. This is extremely useful to perform repetitive tasks or to do what the controlled application was not even design to do.<br /> After a learning curve, everybody can use ARexx as it is built in the system and the scripts can be executed immediately like any other tool.<br /> <br /> = How is my data stored? =<br /> == Files ==<br /> === Executable files ===<br /> Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.<br /> An example is a music player. When you start this executable, the player opens and you can start playing music files.<br /> <br /> AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The laters are executed inside an emulation that transcripts them into PowerPC code.<br /> <br /> ==== Scripts ====<br /> <br /> Scripts are text files containing a list of commands. So they are not strictly executables like ''binary code'' files but they can be executed by AmigaOS like if they were.<br /> This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.<br /> <br /> === Data files ===<br /> Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.<br /> <br /> == Directories/Drawers ==<br /> In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.<br /> Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.<br /> <br /> Note: directories are often called ''folders'' on other systems.<br /> <br /> == Disks, partitions and volumes ==<br /> === Disks ===<br /> Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.<br /> <br /> === Partitions ===<br /> A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.<br /> <br /> [[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]<br /> <br /> On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.<br /> <br /> === Volumes ===<br /> A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.<br /> <br /> = How to identify files/directories =<br /> <br /> == On the Workbench ==<br /> <br /> The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...<br /> <br /> In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.<br /> <br /> == In a shell ==<br /> <br /> In a shell you need to issue the command '''list''' to see if an object is a file or a directory.<br /> <br /> [[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]<br /> <br /> A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.<br /> <br /> Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.<br /> <br /> = All AmigaOS components =<br /> <br /> AmigaOS is made of different components which have their own job in the system. The most important ones are mandatory. Without them the system does not even start. Other components are less important and the user can choose to use them or not. This is the case of drivers. For instance, a device driver may be omitted. If so, the corresponding device will just not work as AmigaOS will have no driver that allows it to know what to do with this device.<br /> <br /> == Kickstart modules ==<br /> <br /> These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is some kind of director handling the work of all other components.<br /> You can find all these modules in the '''Kickstart''' directory in the system volume. Here is a list:<br /> <br /> === Mandatory modules ===<br /> <br /> The following modules are required in any AmigaOS system. Without one of these, the system will not start.<br /> <br /> * kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.<br /> * loader - this component handles the loading of all other kickstart modules<br /> * battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time<br /> * bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS<br /> * bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS<br /> * con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface<br /> * console.device.kmod - it opens a window and reads/writes text to and from that window<br /> * diskboot.kmod - handles the booting of AmigaOS from a supported disk<br /> * diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS<br /> * dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories<br /> * elf.library.kmod - handles the loading of executable programs<br /> * env-handler.kmod - handles the read/writes of environment variables<br /> * FileSystem.resource.kmod - handles the use of the different filesystems<br /> * gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...<br /> * gameport.device.kmod - handles the read/writes of game pads and joysticks<br /> * graphics.library.kmod - collection of functions used to draw graphic elements on the monitor<br /> * hunk.library.kmod - set of functions to read a data stream into memory<br /> * input.device.kmod - handles of input events like keyboard events or mouse clicks<br /> * intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)<br /> * layers.library.kmod - set of functions to be used to handle different layers in graphic operations<br /> * keyboard.device.kmod - driver for the keyboard<br /> * keymap.library.kmod - functions to handle different keymaps<br /> * newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )<br /> * nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage<br /> * nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers<br /> * PCIGraphics.card - driver that supports the use of different graphic cards<br /> * ram-handler.kmod - functions that handles the '''Ram disk:''' special disk<br /> * ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk<br /> * ramlib.kmod - loads disk based libraries and devices for exec.library<br /> * rtg.library - library of functions perform lowlevel graphic operations on graphic cards<br /> * shell.kmod - the AmigaOS command line interface<br /> * strap.kmod - module that handles booting on different disk devices<br /> * timer.device.kmod - driver to give access to timing functions<br /> <br /> === Filesystem support ===<br /> <br /> These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.<br /> <br /> * CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...<br /> * SmartFilesystem - allows to store data on partitions in SFS0 and SFS2<br /> * JXFileSystem - allows to create partitions in JXFS<br /> * FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts<br /> * diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules<br /> <br /> === Hardware drivers ===<br /> <br /> ==== Graphic cards drivers ====<br /> <br /> * 3dfxVoodoo.chip<br /> * 3DLabsPermedia2.chip<br /> * ATIRadeon.chip<br /> * RadeonHD.chip<br /> * siliconmotion502.chip<br /> <br /> ==== Disk drivers ====<br /> <br /> Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.<br /> <br /> * it8212ide.device.kmod<br /> * lsi53c8xx.device.kmod<br /> * sam460sata.device.kmod<br /> * sii3112ide.device.kmod<br /> * sii3512ide.device.kmod<br /> * sii3114ide.device.kmod<br /> * sii0680ide.device.kmod<br /> * sii3132ide.device.kmod<br /> <br /> ==== USB drivers ====<br /> <br /> * hub.usbfd<br /> * usbsys.device<br /> * usbresource.library<br /> * ehci.usbhcd<br /> * ohci.usbhcd<br /> * uhci.usbhcd<br /> * massstorage.usbfd<br /> <br /> ==== Other drivers ====<br /> <br /> * bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded<br /> * bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded<br /> * fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers<br /> * i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers<br /> * xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000<br /> <br /> === Misc modules ===<br /> <br /> * petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor<br /> <br /> == System components ==<br /> <br /> [[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]<br /> <br /> Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.<br /> Here is described a default AmigaOS installation.<br /> <br /> * C<br /> This directory contains AmigaDOS '''C'''ommands<br /> * Classes<br /> contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...<br /> * Devs<br /> contains definition for '''Dev'''ices<br /> * Emulation<br /> contains files used for the 68k emulation (though E-UAE)<br /> * Fonts<br /> contains various systems fonts<br /> * Internet<br /> contains a dialer to connect to Internet<br /> * Kickstart<br /> contains the kickstart modules<br /> * L<br /> contains hand'''l'''ers and filesystems<br /> * Libs<br /> contains dynamic '''Libr'''airies of functions<br /> * Locale<br /> contains all files used to localise the system (catalogs, keymaps...)<br /> * MUI<br /> contains the needed files for programs that use the MUI third party graphic interface<br /> * Prefs<br /> contains the preference programs used to customise AmigaOS<br /> * S<br /> contains the '''S'''cripts<br /> * SObjs<br /> contains .so shared object library files<br /> * Storage<br /> contains other optional files<br /> * System<br /> contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools<br /> * Utilities<br /> contains several utilities<br /> <br /> = Motorola 680x0 Emulators =<br /> <br /> For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.<br /> <br /> In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be &quot;switched off&quot;.<br /> <br /> Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. &quot;Native&quot; PowerPC programs were rare, and every time a PowerPC program called the system, a so called &quot;context switch&quot; occurred between the 680x0 and PowerPC code, often causing a large performance penalty.<br /> <br /> The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor. <br /> <br /> == Two 680x0 Emulators ==<br /> <br /> In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low &quot;reaction time&quot;, and is ideal for time critical parts, such as interrupts.<br /> <br /> The other is Petunia, the &quot;JIT emulator&quot;. A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.<br /> <br /> Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, &quot;on the fly&quot;.<br /> <br /> This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.<br /> <br /> == Features ==<br /> <br /> Emulated opcodes:<br /> * all user and supervisor level opcodes of the Motorola 68040<br /> * all FPU opcodes of the Motorola 68881/68882 <br /> <br /> AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.<br /> <br /> At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.<br /> <br /> == Removing the JIT Emulator ==<br /> <br /> Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.<br /> <br /> If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.<br /> <br /> Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the &quot;Sys:Kickstart/Kicklayout&quot; file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like &quot;DefaultJIT&quot;, or &quot;DefaultNoJIT&quot;.<br /> <br /> == Configuring the Emulators ==<br /> <br /> Petunia cooperates with a so called &quot;black list&quot;. By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.<br /> <br /> If an executable needs to be added to the list, then it can be done by extending the file &quot;DEVS:applications.dos&quot; with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.<br /> <br /> Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.<br /> <br /> Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.<br /> <br /> For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list. <br /> <br /> = AmigaOS boot procedure =<br /> <br /> Basically a computer with AmigaOS does the following when the power button is pushed:<br /> <br /> * [[File:Uboot.jpg|200px]]<br /> the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.<br /> * depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.<br /> * [[File:SLB.png|200px]]<br /> the SLB will analyses all Amiga partitions and read each [[UserDoc:kickstart_configuration|system configuration]] it finds. It will show all available configurations for the user to select one to load.<br /> The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.<br /> * [[File:Kmods loading.png|200px]]<br /> the SLB loads the kickstart files of the selected configuration<br /> * SLB executes the '''Loader''' module<br /> * '''Loader''' executes the kickstart modules (Exec, devices, libraries...)<br /> * AmigaOS becomes alive displaying a boot picture on the monitor<br /> * the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume<br /> * the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.<br /> * the Workbench is started<br /> <br /> At this point the user can use his/her computer.<br /> <br /> = How to make a Bootable USB Memory Stick for AmigaOS 4.1 =<br /> <br /> By Julian Margetson (&quot;Spectre660&quot;)<br /> <br /> Prerequisites:<br /> * USB memory stick of 2 GB or less in size.<br /> * It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.<br /> * Plug the USB memory stick into a USB port on your machine.<br /> * Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.<br /> <br /> Procedure:<br /> # You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.<br /> # Make certain that you have selected usbdisk.device and not any other device.<br /> # Click on &quot;Start&quot;<br /> # You will see the usb mass storage unit connected in a list.<br /> # Make sure that the Unit type displayed for the USB memory stick is &quot;Removable hard disk&quot;<br /> # Select that Unit by clicking on it.<br /> # The first thing that you need to do is to install the RDB onto the USB Memory Stick.<br /> # Click on the &quot;Install&quot; button.<br /> # A window Labeled &quot;RDB/disk geometry editing&quot; comes up.<br /> ## Towards the bottom of the window is the &quot;AmigaOne boot code (SLB)&quot; section.<br /> ## Select the &quot;Install&quot; button .<br /> ## A file requester &quot;Select AmigaOne Boot Code&quot; now comes up with the Drawer choice defaulting to &quot;l:&quot;<br /> ## Select file &quot;slb_v2&quot;. <br /> ## Select Ok.<br /> ## You are now returned to the &quot;RDB/disk geometry editing window&quot;.<br /> ## Select &quot;Ok-accept changes&quot;.<br /> # You are now returned to the display showing the attached USB unit.<br /> # Select &quot;Edit partitions and Filesystems&quot;. You will now see the Window 'Editing partitions for disk&quot;<br /> # Select &quot;Add partition&quot;<br /> # This defaults to using the whole device as a single partition.<br /> # It is possible to use create more partitions but for this tutorial we will only use one.<br /> # You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the &quot;Name&quot; box.<br /> # Now make sure that the Boxes &quot;Automount&quot; and &quot;Bootable&quot; are selected and show the &quot;Tick mark&quot;.<br /> # You need to set &quot;Boot priority&quot; to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the &quot;+&quot; to the right of the &quot;boot priority&quot; box. Normally you can set the boot priority to 2 .<br /> # Next it is time to select the file system to use.<br /> # Select &quot;Select filesystem/edit details&quot;.<br /> # The Window &quot;Editing details for partition 'USB0'&quot; ,or whatever partition name you used, comes up.<br /> ## Select the file system that you are going to use by selecting the pull down menu under &quot;Filesystem chooser&quot;.<br /> ## Only filesystems SFS/00 or SFS/02 will work for a bootable device.<br /> ## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.<br /> ## Next select Blocksize from the &quot;Blocksize&quot; pull down menu. 512 is the correct size to use.<br /> ## Now Select &quot;Ok-accept changes&quot;.<br /> ## Your are now returned to the &quot;Edit partitions for disk&quot; window.<br /> ## Again select &quot;Ok-accept changes&quot;<br /> # You are now returned to the window showing the USB mass storage unit list.<br /> # Select &quot;Save to disk&quot;<br /> # A requester pops up with the options &quot;Yes, Save.&quot; or &quot;No!&quot;<br /> # Select the &quot;Yes, save.&quot; option.<br /> # You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.<br /> # This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.<br /> # Select &quot;Yes, reboot NOW!&quot;.<br /> # Once you have rebooted connect your USB Memory Stick to a USB port.<br /> # A disk icon &quot;USB0:Uninitialized&quot; (or whatever partition name you used) appears on Workbench.<br /> # You now need to format the device.<br /> # To format Select this Icon and go to the Workbench &quot;Icons&quot; menu .<br /> # Select &quot;Format Disk&quot;<br /> # You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.<br /> # You can use either a full Format or a Quick Format. Full Format may take a few minutes.<br /> # Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=UserDoc:How_AmigaOS_Works&diff=6213 UserDoc:How AmigaOS Works 2013-07-29T20:44:08Z <p>Philippe Ferrucci: /* AmigaOS boot procedure */</p> <hr /> <div>As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.<br /> <br /> In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.<br /> <br /> = The most important components =<br /> <br /> == Exec, the AmigaOS kernel ==<br /> <br /> Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible of running programs, dealing with computer memory, managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.<br /> <br /> It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.<br /> <br /> == AmigaDOS: the underlying system ==<br /> <br /> The word &quot;DOS&quot; was originally an acronym for &quot;Disk Operating System&quot;. Some say it should be &quot;Disk Based Operating System&quot; as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be &quot;Device Operating System&quot;.<br /> <br /> The whole AmigaDOS system includes things such as:<br /> <br /> * A set of commands that can be used in the Shell window and elsewhere.<br /> * A system for saving data to disk and retrieving it from disk.<br /> * A system for filing data on disks.<br /> * An interface for peripherals such as keyboards, monitors, printers, etc.<br /> * A method of running programs<br /> * A multitasking system for running more than one program at a time.<br /> * etc. etc. etc.<br /> <br /> Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.<br /> <br /> == The Graphics library ==<br /> <br /> The Graphics library handles every low level graphic operations like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.<br /> <br /> == Intuition ==<br /> <br /> The Intuition library is responsible for every graphical objects: windows, screens, gadgets, mouse pointers... It lays between any graphic program and the graphics library.<br /> <br /> == The Workbench ==<br /> <br /> The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.<br /> [[File:Wb.png|320px]]<br /> <br /> == ARexx - inter-program communication by scripting ==<br /> <br /> The ARexx scripting language can be used to operate the Workbench and the most important Amiga applications from a script containing ARexx commands. This is extremely useful to perform repetitive tasks or to do what the controlled application was not even design to do.<br /> After a learning curve, everybody can use ARexx as it is built in the system and the scripts can be executed immediately like any other tool.<br /> <br /> = How is my data stored? =<br /> == Files ==<br /> === Executable files ===<br /> Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.<br /> An example is a music player. When you start this executable, the player opens and you can start playing music files.<br /> <br /> AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The laters are executed inside an emulation that transcripts them into PowerPC code.<br /> <br /> ==== Scripts ====<br /> <br /> Scripts are text files containing a list of commands. So they are not strictly executables like ''binary code'' files but they can be executed by AmigaOS like if they were.<br /> This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.<br /> <br /> === Data files ===<br /> Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.<br /> <br /> == Directories/Drawers ==<br /> In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.<br /> Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.<br /> <br /> Note: directories are often called ''folders'' on other systems.<br /> <br /> == Disks, partitions and volumes ==<br /> === Disks ===<br /> Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.<br /> <br /> === Partitions ===<br /> A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.<br /> <br /> [[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]<br /> <br /> On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.<br /> <br /> === Volumes ===<br /> A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.<br /> <br /> = How to identify files/directories =<br /> <br /> == On the Workbench ==<br /> <br /> The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...<br /> <br /> In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.<br /> <br /> == In a shell ==<br /> <br /> In a shell you need to issue the command '''list''' to see if an object is a file or a directory.<br /> <br /> [[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]<br /> <br /> A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.<br /> <br /> Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.<br /> <br /> = All AmigaOS components =<br /> <br /> AmigaOS is made of different components which have their own job in the system. The most important ones are mandatory. Without them the system does not even start. Other components are less important and the user can choose to use them or not. This is the case of drivers. For instance, a device driver may be omitted. If so, the corresponding device will just not work as AmigaOS will have no driver that allows it to know what to do with this device.<br /> <br /> == Kickstart modules ==<br /> <br /> These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is some kind of director handling the work of all other components.<br /> You can find all these modules in the '''Kickstart''' directory in the system volume. Here is a list:<br /> <br /> === Mandatory modules ===<br /> <br /> The following modules are required in any AmigaOS system. Without one of these, the system will not start.<br /> <br /> * kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.<br /> * loader - this component handles the loading of all other kickstart modules<br /> * battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time<br /> * bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS<br /> * bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS<br /> * con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface<br /> * console.device.kmod - it opens a window and reads/writes text to and from that window<br /> * diskboot.kmod - handles the booting of AmigaOS from a supported disk<br /> * diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS<br /> * dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories<br /> * elf.library.kmod - handles the loading of executable programs<br /> * env-handler.kmod - handles the read/writes of environment variables<br /> * FileSystem.resource.kmod - handles the use of the different filesystems<br /> * gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...<br /> * gameport.device.kmod - handles the read/writes of game pads and joysticks<br /> * graphics.library.kmod - collection of functions used to draw graphic elements on the monitor<br /> * hunk.library.kmod - set of functions to read a data stream into memory<br /> * input.device.kmod - handles of input events like keyboard events or mouse clicks<br /> * intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)<br /> * layers.library.kmod - set of functions to be used to handle different layers in graphic operations<br /> * keyboard.device.kmod - driver for the keyboard<br /> * keymap.library.kmod - functions to handle different keymaps<br /> * newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )<br /> * nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage<br /> * nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers<br /> * PCIGraphics.card - driver that supports the use of different graphic cards<br /> * ram-handler.kmod - functions that handles the '''Ram disk:''' special disk<br /> * ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk<br /> * ramlib.kmod - loads disk based libraries and devices for exec.library<br /> * rtg.library - library of functions perform lowlevel graphic operations on graphic cards<br /> * shell.kmod - the AmigaOS command line interface<br /> * strap.kmod - module that handles booting on different disk devices<br /> * timer.device.kmod - driver to give access to timing functions<br /> <br /> === Filesystem support ===<br /> <br /> These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.<br /> <br /> * CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...<br /> * SmartFilesystem - allows to store data on partitions in SFS0 and SFS2<br /> * JXFileSystem - allows to create partitions in JXFS<br /> * FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts<br /> * diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules<br /> <br /> === Hardware drivers ===<br /> <br /> ==== Graphic cards drivers ====<br /> <br /> * 3dfxVoodoo.chip<br /> * 3DLabsPermedia2.chip<br /> * ATIRadeon.chip<br /> * RadeonHD.chip<br /> * siliconmotion502.chip<br /> <br /> ==== Disk drivers ====<br /> <br /> Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.<br /> <br /> * it8212ide.device.kmod<br /> * lsi53c8xx.device.kmod<br /> * sam460sata.device.kmod<br /> * sii3112ide.device.kmod<br /> * sii3512ide.device.kmod<br /> * sii3114ide.device.kmod<br /> * sii0680ide.device.kmod<br /> * sii3132ide.device.kmod<br /> <br /> ==== USB drivers ====<br /> <br /> * hub.usbfd<br /> * usbsys.device<br /> * usbresource.library<br /> * ehci.usbhcd<br /> * ohci.usbhcd<br /> * uhci.usbhcd<br /> * massstorage.usbfd<br /> <br /> ==== Other drivers ====<br /> <br /> * bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded<br /> * bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded<br /> * fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers<br /> * i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers<br /> * xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000<br /> <br /> === Misc modules ===<br /> <br /> * petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor<br /> <br /> == System components ==<br /> <br /> [[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]<br /> <br /> Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.<br /> Here is described a default AmigaOS installation.<br /> <br /> * C<br /> This directory contains AmigaDOS '''C'''ommands<br /> * Classes<br /> contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...<br /> * Devs<br /> contains definition for '''Dev'''ices<br /> * Emulation<br /> contains files used for the 68k emulation (though E-UAE)<br /> * Fonts<br /> contains various systems fonts<br /> * Internet<br /> contains a dialer to connect to Internet<br /> * Kickstart<br /> contains the kickstart modules<br /> * L<br /> contains hand'''l'''ers and filesystems<br /> * Libs<br /> contains dynamic '''Libr'''airies of functions<br /> * Locale<br /> contains all files used to localise the system (catalogs, keymaps...)<br /> * MUI<br /> contains the needed files for programs that use the MUI third party graphic interface<br /> * Prefs<br /> contains the preference programs used to customise AmigaOS<br /> * S<br /> contains the '''S'''cripts<br /> * SObjs<br /> contains .so shared object library files<br /> * Storage<br /> contains other optional files<br /> * System<br /> contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools<br /> * Utilities<br /> contains several utilities<br /> <br /> = Motorola 680x0 Emulators =<br /> <br /> For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.<br /> <br /> In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be &quot;switched off&quot;.<br /> <br /> Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. &quot;Native&quot; PowerPC programs were rare, and every time a PowerPC program called the system, a so called &quot;context switch&quot; occurred between the 680x0 and PowerPC code, often causing a large performance penalty.<br /> <br /> The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor. <br /> <br /> == Two 680x0 Emulators ==<br /> <br /> In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low &quot;reaction time&quot;, and is ideal for time critical parts, such as interrupts.<br /> <br /> The other is Petunia, the &quot;JIT emulator&quot;. A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.<br /> <br /> Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, &quot;on the fly&quot;.<br /> <br /> This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.<br /> <br /> == Features ==<br /> <br /> Emulated opcodes:<br /> * all user and supervisor level opcodes of the Motorola 68040<br /> * all FPU opcodes of the Motorola 68881/68882 <br /> <br /> AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.<br /> <br /> At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.<br /> <br /> == Removing the JIT Emulator ==<br /> <br /> Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.<br /> <br /> If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.<br /> <br /> Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the &quot;Sys:Kickstart/Kicklayout&quot; file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like &quot;DefaultJIT&quot;, or &quot;DefaultNoJIT&quot;.<br /> <br /> == Configuring the Emulators ==<br /> <br /> Petunia cooperates with a so called &quot;black list&quot;. By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.<br /> <br /> If an executable needs to be added to the list, then it can be done by extending the file &quot;DEVS:applications.dos&quot; with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.<br /> <br /> Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.<br /> <br /> Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.<br /> <br /> For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list. <br /> <br /> = AmigaOS boot procedure =<br /> <br /> Basically a computer with AmigaOS does the following when the power button is pushed:<br /> <br /> * [[File:Uboot.jpg|200px]]<br /> the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.<br /> * depending on how you setup the BIOS it will look on the harddisk to find the Second Level Booter (SLB). This program is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files. In other words, it is the link between the BIOS and the rest of the boot procedure. Its goal is also to give you the ability to start several configurations present on the same drive.<br /> * [[File:SLB.png|200px]]<br /> the SLB will analyses all Amiga partitions and read each [[UserDoc:kickstart_configuration|system configuration]] it finds. It will show all available configurations for the user to select one to load.<br /> The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.<br /> * [[File:Kmods loading.png|200px]]<br /> the SLB loads the kickstart files of the selected configuration<br /> * SLB executes the '''Loader''' module<br /> * '''Loader''' executes the kickstart modules (Exec, devices, libraries...)<br /> * AmigaOS becomes alive displaying a boot picture on the monitor<br /> * the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume<br /> * the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.<br /> * the Workbench is started<br /> <br /> At this point the user can use his/her computer.<br /> <br /> = How to make a Bootable USB Memory Stick for AmigaOS 4.1 =<br /> <br /> By Julian Margetson (&quot;Spectre660&quot;)<br /> <br /> Prerequisites:<br /> * USB memory stick of 2 GB or less in size.<br /> * It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.<br /> * Plug the USB memory stick into a USB port on your machine.<br /> * Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.<br /> <br /> Procedure:<br /> # You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.<br /> # Make certain that you have selected usbdisk.device and not any other device.<br /> # Click on &quot;Start&quot;<br /> # You will see the usb mass storage unit connected in a list.<br /> # Make sure that the Unit type displayed for the USB memory stick is &quot;Removable hard disk&quot;<br /> # Select that Unit by clicking on it.<br /> # The first thing that you need to do is to install the RDB onto the USB Memory Stick.<br /> # Click on the &quot;Install&quot; button.<br /> # A window Labeled &quot;RDB/disk geometry editing&quot; comes up.<br /> ## Towards the bottom of the window is the &quot;AmigaOne boot code (SLB)&quot; section.<br /> ## Select the &quot;Install&quot; button .<br /> ## A file requester &quot;Select AmigaOne Boot Code&quot; now comes up with the Drawer choice defaulting to &quot;l:&quot;<br /> ## Select file &quot;slb_v2&quot;. <br /> ## Select Ok.<br /> ## You are now returned to the &quot;RDB/disk geometry editing window&quot;.<br /> ## Select &quot;Ok-accept changes&quot;.<br /> # You are now returned to the display showing the attached USB unit.<br /> # Select &quot;Edit partitions and Filesystems&quot;. You will now see the Window 'Editing partitions for disk&quot;<br /> # Select &quot;Add partition&quot;<br /> # This defaults to using the whole device as a single partition.<br /> # It is possible to use create more partitions but for this tutorial we will only use one.<br /> # You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the &quot;Name&quot; box.<br /> # Now make sure that the Boxes &quot;Automount&quot; and &quot;Bootable&quot; are selected and show the &quot;Tick mark&quot;.<br /> # You need to set &quot;Boot priority&quot; to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the &quot;+&quot; to the right of the &quot;boot priority&quot; box. Normally you can set the boot priority to 2 .<br /> # Next it is time to select the file system to use.<br /> # Select &quot;Select filesystem/edit details&quot;.<br /> # The Window &quot;Editing details for partition 'USB0'&quot; ,or whatever partition name you used, comes up.<br /> ## Select the file system that you are going to use by selecting the pull down menu under &quot;Filesystem chooser&quot;.<br /> ## Only filesystems SFS/00 or SFS/02 will work for a bootable device.<br /> ## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.<br /> ## Next select Blocksize from the &quot;Blocksize&quot; pull down menu. 512 is the correct size to use.<br /> ## Now Select &quot;Ok-accept changes&quot;.<br /> ## Your are now returned to the &quot;Edit partitions for disk&quot; window.<br /> ## Again select &quot;Ok-accept changes&quot;<br /> # You are now returned to the window showing the USB mass storage unit list.<br /> # Select &quot;Save to disk&quot;<br /> # A requester pops up with the options &quot;Yes, Save.&quot; or &quot;No!&quot;<br /> # Select the &quot;Yes, save.&quot; option.<br /> # You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.<br /> # This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.<br /> # Select &quot;Yes, reboot NOW!&quot;.<br /> # Once you have rebooted connect your USB Memory Stick to a USB port.<br /> # A disk icon &quot;USB0:Uninitialized&quot; (or whatever partition name you used) appears on Workbench.<br /> # You now need to format the device.<br /> # To format Select this Icon and go to the Workbench &quot;Icons&quot; menu .<br /> # Select &quot;Format Disk&quot;<br /> # You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.<br /> # You can use either a full Format or a Quick Format. Full Format may take a few minutes.<br /> # Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=UserDoc:How_AmigaOS_Works&diff=6212 UserDoc:How AmigaOS Works 2013-07-29T20:35:28Z <p>Philippe Ferrucci: /* AmigaOS boot procedure */</p> <hr /> <div>As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.<br /> <br /> In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.<br /> <br /> = The most important components =<br /> <br /> == Exec, the AmigaOS kernel ==<br /> <br /> Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible of running programs, dealing with computer memory, managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.<br /> <br /> It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.<br /> <br /> == AmigaDOS: the underlying system ==<br /> <br /> The word &quot;DOS&quot; was originally an acronym for &quot;Disk Operating System&quot;. Some say it should be &quot;Disk Based Operating System&quot; as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be &quot;Device Operating System&quot;.<br /> <br /> The whole AmigaDOS system includes things such as:<br /> <br /> * A set of commands that can be used in the Shell window and elsewhere.<br /> * A system for saving data to disk and retrieving it from disk.<br /> * A system for filing data on disks.<br /> * An interface for peripherals such as keyboards, monitors, printers, etc.<br /> * A method of running programs<br /> * A multitasking system for running more than one program at a time.<br /> * etc. etc. etc.<br /> <br /> Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.<br /> <br /> == The Graphics library ==<br /> <br /> The Graphics library handles every low level graphic operations like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.<br /> <br /> == Intuition ==<br /> <br /> The Intuition library is responsible for every graphical objects: windows, screens, gadgets, mouse pointers... It lays between any graphic program and the graphics library.<br /> <br /> == The Workbench ==<br /> <br /> The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.<br /> [[File:Wb.png|320px]]<br /> <br /> == ARexx - inter-program communication by scripting ==<br /> <br /> The ARexx scripting language can be used to operate the Workbench and the most important Amiga applications from a script containing ARexx commands. This is extremely useful to perform repetitive tasks or to do what the controlled application was not even design to do.<br /> After a learning curve, everybody can use ARexx as it is built in the system and the scripts can be executed immediately like any other tool.<br /> <br /> = How is my data stored? =<br /> == Files ==<br /> === Executable files ===<br /> Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.<br /> An example is a music player. When you start this executable, the player opens and you can start playing music files.<br /> <br /> AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The laters are executed inside an emulation that transcripts them into PowerPC code.<br /> <br /> ==== Scripts ====<br /> <br /> Scripts are text files containing a list of commands. So they are not strictly executables like ''binary code'' files but they can be executed by AmigaOS like if they were.<br /> This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.<br /> <br /> === Data files ===<br /> Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.<br /> <br /> == Directories/Drawers ==<br /> In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.<br /> Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.<br /> <br /> Note: directories are often called ''folders'' on other systems.<br /> <br /> == Disks, partitions and volumes ==<br /> === Disks ===<br /> Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.<br /> <br /> === Partitions ===<br /> A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.<br /> <br /> [[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]<br /> <br /> On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.<br /> <br /> === Volumes ===<br /> A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.<br /> <br /> = How to identify files/directories =<br /> <br /> == On the Workbench ==<br /> <br /> The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...<br /> <br /> In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.<br /> <br /> == In a shell ==<br /> <br /> In a shell you need to issue the command '''list''' to see if an object is a file or a directory.<br /> <br /> [[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]<br /> <br /> A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.<br /> <br /> Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.<br /> <br /> = All AmigaOS components =<br /> <br /> AmigaOS is made of different components which have their own job in the system. The most important ones are mandatory. Without them the system does not even start. Other components are less important and the user can choose to use them or not. This is the case of drivers. For instance, a device driver may be omitted. If so, the corresponding device will just not work as AmigaOS will have no driver that allows it to know what to do with this device.<br /> <br /> == Kickstart modules ==<br /> <br /> These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is some kind of director handling the work of all other components.<br /> You can find all these modules in the '''Kickstart''' directory in the system volume. Here is a list:<br /> <br /> === Mandatory modules ===<br /> <br /> The following modules are required in any AmigaOS system. Without one of these, the system will not start.<br /> <br /> * kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.<br /> * loader - this component handles the loading of all other kickstart modules<br /> * battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time<br /> * bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS<br /> * bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS<br /> * con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface<br /> * console.device.kmod - it opens a window and reads/writes text to and from that window<br /> * diskboot.kmod - handles the booting of AmigaOS from a supported disk<br /> * diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS<br /> * dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories<br /> * elf.library.kmod - handles the loading of executable programs<br /> * env-handler.kmod - handles the read/writes of environment variables<br /> * FileSystem.resource.kmod - handles the use of the different filesystems<br /> * gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...<br /> * gameport.device.kmod - handles the read/writes of game pads and joysticks<br /> * graphics.library.kmod - collection of functions used to draw graphic elements on the monitor<br /> * hunk.library.kmod - set of functions to read a data stream into memory<br /> * input.device.kmod - handles of input events like keyboard events or mouse clicks<br /> * intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)<br /> * layers.library.kmod - set of functions to be used to handle different layers in graphic operations<br /> * keyboard.device.kmod - driver for the keyboard<br /> * keymap.library.kmod - functions to handle different keymaps<br /> * newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )<br /> * nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage<br /> * nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers<br /> * PCIGraphics.card - driver that supports the use of different graphic cards<br /> * ram-handler.kmod - functions that handles the '''Ram disk:''' special disk<br /> * ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk<br /> * ramlib.kmod - loads disk based libraries and devices for exec.library<br /> * rtg.library - library of functions perform lowlevel graphic operations on graphic cards<br /> * shell.kmod - the AmigaOS command line interface<br /> * strap.kmod - module that handles booting on different disk devices<br /> * timer.device.kmod - driver to give access to timing functions<br /> <br /> === Filesystem support ===<br /> <br /> These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.<br /> <br /> * CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...<br /> * SmartFilesystem - allows to store data on partitions in SFS0 and SFS2<br /> * JXFileSystem - allows to create partitions in JXFS<br /> * FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts<br /> * diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules<br /> <br /> === Hardware drivers ===<br /> <br /> ==== Graphic cards drivers ====<br /> <br /> * 3dfxVoodoo.chip<br /> * 3DLabsPermedia2.chip<br /> * ATIRadeon.chip<br /> * RadeonHD.chip<br /> * siliconmotion502.chip<br /> <br /> ==== Disk drivers ====<br /> <br /> Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.<br /> <br /> * it8212ide.device.kmod<br /> * lsi53c8xx.device.kmod<br /> * sam460sata.device.kmod<br /> * sii3112ide.device.kmod<br /> * sii3512ide.device.kmod<br /> * sii3114ide.device.kmod<br /> * sii0680ide.device.kmod<br /> * sii3132ide.device.kmod<br /> <br /> ==== USB drivers ====<br /> <br /> * hub.usbfd<br /> * usbsys.device<br /> * usbresource.library<br /> * ehci.usbhcd<br /> * ohci.usbhcd<br /> * uhci.usbhcd<br /> * massstorage.usbfd<br /> <br /> ==== Other drivers ====<br /> <br /> * bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded<br /> * bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded<br /> * fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers<br /> * i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers<br /> * xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000<br /> <br /> === Misc modules ===<br /> <br /> * petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor<br /> <br /> == System components ==<br /> <br /> [[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]<br /> <br /> Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.<br /> Here is described a default AmigaOS installation.<br /> <br /> * C<br /> This directory contains AmigaDOS '''C'''ommands<br /> * Classes<br /> contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...<br /> * Devs<br /> contains definition for '''Dev'''ices<br /> * Emulation<br /> contains files used for the 68k emulation (though E-UAE)<br /> * Fonts<br /> contains various systems fonts<br /> * Internet<br /> contains a dialer to connect to Internet<br /> * Kickstart<br /> contains the kickstart modules<br /> * L<br /> contains hand'''l'''ers and filesystems<br /> * Libs<br /> contains dynamic '''Libr'''airies of functions<br /> * Locale<br /> contains all files used to localise the system (catalogs, keymaps...)<br /> * MUI<br /> contains the needed files for programs that use the MUI third party graphic interface<br /> * Prefs<br /> contains the preference programs used to customise AmigaOS<br /> * S<br /> contains the '''S'''cripts<br /> * SObjs<br /> contains .so shared object library files<br /> * Storage<br /> contains other optional files<br /> * System<br /> contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools<br /> * Utilities<br /> contains several utilities<br /> <br /> = Motorola 680x0 Emulators =<br /> <br /> For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.<br /> <br /> In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be &quot;switched off&quot;.<br /> <br /> Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. &quot;Native&quot; PowerPC programs were rare, and every time a PowerPC program called the system, a so called &quot;context switch&quot; occurred between the 680x0 and PowerPC code, often causing a large performance penalty.<br /> <br /> The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor. <br /> <br /> == Two 680x0 Emulators ==<br /> <br /> In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low &quot;reaction time&quot;, and is ideal for time critical parts, such as interrupts.<br /> <br /> The other is Petunia, the &quot;JIT emulator&quot;. A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.<br /> <br /> Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, &quot;on the fly&quot;.<br /> <br /> This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.<br /> <br /> == Features ==<br /> <br /> Emulated opcodes:<br /> * all user and supervisor level opcodes of the Motorola 68040<br /> * all FPU opcodes of the Motorola 68881/68882 <br /> <br /> AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.<br /> <br /> At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.<br /> <br /> == Removing the JIT Emulator ==<br /> <br /> Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.<br /> <br /> If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.<br /> <br /> Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the &quot;Sys:Kickstart/Kicklayout&quot; file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like &quot;DefaultJIT&quot;, or &quot;DefaultNoJIT&quot;.<br /> <br /> == Configuring the Emulators ==<br /> <br /> Petunia cooperates with a so called &quot;black list&quot;. By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.<br /> <br /> If an executable needs to be added to the list, then it can be done by extending the file &quot;DEVS:applications.dos&quot; with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.<br /> <br /> Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.<br /> <br /> Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.<br /> <br /> For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list. <br /> <br /> = AmigaOS boot procedure =<br /> <br /> Basically a computer with AmigaOS does the following when the power button is pushed:<br /> <br /> * [[File:Uboot.jpg|200px]] the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed. This allows to see if hardware is correctly recognised. As an example you can see if a hard drive is correctly connected into the machine and your BIOS is correctly setup to make this drive useable.<br /> * the BIOS looks on the harddisk and finds a file called the Second Level Booter (SLB). It is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files.<br /> * [[File:SLB.png|200px]] the SLB will analyses all Amiga partitions and read each [[UserDoc:kickstart_configuration|system configuration]] it finds. It will show all available configurations for the user to select one to load.<br /> The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.<br /> * [[File:Kmods loading.png|200px]] the SLB loads the kickstart files of the selected configuration<br /> * SLB executes the '''Loader''' module<br /> * '''Loader''' executes the kickstart modules (Exec, devices, libraries...)<br /> * AmigaOS becomes alive displaying a boot picture on the monitor<br /> * the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume<br /> * the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.<br /> * the Workbench is started<br /> <br /> At this point the user can use his/her computer.<br /> <br /> = How to make a Bootable USB Memory Stick for AmigaOS 4.1 =<br /> <br /> By Julian Margetson (&quot;Spectre660&quot;)<br /> <br /> Prerequisites:<br /> * USB memory stick of 2 GB or less in size.<br /> * It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.<br /> * Plug the USB memory stick into a USB port on your machine.<br /> * Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.<br /> <br /> Procedure:<br /> # You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.<br /> # Make certain that you have selected usbdisk.device and not any other device.<br /> # Click on &quot;Start&quot;<br /> # You will see the usb mass storage unit connected in a list.<br /> # Make sure that the Unit type displayed for the USB memory stick is &quot;Removable hard disk&quot;<br /> # Select that Unit by clicking on it.<br /> # The first thing that you need to do is to install the RDB onto the USB Memory Stick.<br /> # Click on the &quot;Install&quot; button.<br /> # A window Labeled &quot;RDB/disk geometry editing&quot; comes up.<br /> ## Towards the bottom of the window is the &quot;AmigaOne boot code (SLB)&quot; section.<br /> ## Select the &quot;Install&quot; button .<br /> ## A file requester &quot;Select AmigaOne Boot Code&quot; now comes up with the Drawer choice defaulting to &quot;l:&quot;<br /> ## Select file &quot;slb_v2&quot;. <br /> ## Select Ok.<br /> ## You are now returned to the &quot;RDB/disk geometry editing window&quot;.<br /> ## Select &quot;Ok-accept changes&quot;.<br /> # You are now returned to the display showing the attached USB unit.<br /> # Select &quot;Edit partitions and Filesystems&quot;. You will now see the Window 'Editing partitions for disk&quot;<br /> # Select &quot;Add partition&quot;<br /> # This defaults to using the whole device as a single partition.<br /> # It is possible to use create more partitions but for this tutorial we will only use one.<br /> # You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the &quot;Name&quot; box.<br /> # Now make sure that the Boxes &quot;Automount&quot; and &quot;Bootable&quot; are selected and show the &quot;Tick mark&quot;.<br /> # You need to set &quot;Boot priority&quot; to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the &quot;+&quot; to the right of the &quot;boot priority&quot; box. Normally you can set the boot priority to 2 .<br /> # Next it is time to select the file system to use.<br /> # Select &quot;Select filesystem/edit details&quot;.<br /> # The Window &quot;Editing details for partition 'USB0'&quot; ,or whatever partition name you used, comes up.<br /> ## Select the file system that you are going to use by selecting the pull down menu under &quot;Filesystem chooser&quot;.<br /> ## Only filesystems SFS/00 or SFS/02 will work for a bootable device.<br /> ## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.<br /> ## Next select Blocksize from the &quot;Blocksize&quot; pull down menu. 512 is the correct size to use.<br /> ## Now Select &quot;Ok-accept changes&quot;.<br /> ## Your are now returned to the &quot;Edit partitions for disk&quot; window.<br /> ## Again select &quot;Ok-accept changes&quot;<br /> # You are now returned to the window showing the USB mass storage unit list.<br /> # Select &quot;Save to disk&quot;<br /> # A requester pops up with the options &quot;Yes, Save.&quot; or &quot;No!&quot;<br /> # Select the &quot;Yes, save.&quot; option.<br /> # You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.<br /> # This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.<br /> # Select &quot;Yes, reboot NOW!&quot;.<br /> # Once you have rebooted connect your USB Memory Stick to a USB port.<br /> # A disk icon &quot;USB0:Uninitialized&quot; (or whatever partition name you used) appears on Workbench.<br /> # You now need to format the device.<br /> # To format Select this Icon and go to the Workbench &quot;Icons&quot; menu .<br /> # Select &quot;Format Disk&quot;<br /> # You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.<br /> # You can use either a full Format or a Quick Format. Full Format may take a few minutes.<br /> # Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=UserDoc:How_AmigaOS_Works&diff=6211 UserDoc:How AmigaOS Works 2013-07-29T20:27:37Z <p>Philippe Ferrucci: /* AmigaOS boot procedure */</p> <hr /> <div>As already mentioned, AmigaOS was a pioneer in the early days of personal computing in delivering sophistication that contemporary systems could only have dreamt of and pretended to offer. Today, AmigaOS continues to offer a straightforward elegance that seems to be overlooked in the development of other platforms. Thanks to the concepts behind AmigaOS, the system is easy to understand and to use by everyone.<br /> <br /> In this page we will explore all these concepts of AmigaOS. Also you will learn here the naming of all parts of the system.<br /> <br /> = The most important components =<br /> <br /> == Exec, the AmigaOS kernel ==<br /> <br /> Exec is the kernel of AmigaOS. It is the component that pilots all other components. It is responsible of running programs, dealing with computer memory, managing low-level resources that programs may need. In other words, it organises everything to make the operating system run.<br /> <br /> It is made of different parts that cannot be moved outside the kernel: the scheduler, the memory pager and the 68k interpretive emulator.<br /> <br /> == AmigaDOS: the underlying system ==<br /> <br /> The word &quot;DOS&quot; was originally an acronym for &quot;Disk Operating System&quot;. Some say it should be &quot;Disk Based Operating System&quot; as it does a lot more than operate a disk and that it was really an operating system based (stored) on disks. Some say it should be &quot;Device Operating System&quot;.<br /> <br /> The whole AmigaDOS system includes things such as:<br /> <br /> * A set of commands that can be used in the Shell window and elsewhere.<br /> * A system for saving data to disk and retrieving it from disk.<br /> * A system for filing data on disks.<br /> * An interface for peripherals such as keyboards, monitors, printers, etc.<br /> * A method of running programs<br /> * A multitasking system for running more than one program at a time.<br /> * etc. etc. etc.<br /> <br /> Read the [[AmigaDOS manual]] to understand and learn everything about AmigaDOS.<br /> <br /> == The Graphics library ==<br /> <br /> The Graphics library handles every low level graphic operations like designing pixels on the monitor, creating graphic elements (bobs, sprites) and also writing text output.<br /> <br /> == Intuition ==<br /> <br /> The Intuition library is responsible for every graphical objects: windows, screens, gadgets, mouse pointers... It lays between any graphic program and the graphics library.<br /> <br /> == The Workbench ==<br /> <br /> The Workbench is the graphical place where you will manage your computer and all your files. The name was chosen because the user will use tools to create and work with the computer.<br /> [[File:Wb.png|320px]]<br /> <br /> == ARexx - inter-program communication by scripting ==<br /> <br /> The ARexx scripting language can be used to operate the Workbench and the most important Amiga applications from a script containing ARexx commands. This is extremely useful to perform repetitive tasks or to do what the controlled application was not even design to do.<br /> After a learning curve, everybody can use ARexx as it is built in the system and the scripts can be executed immediately like any other tool.<br /> <br /> = How is my data stored? =<br /> == Files ==<br /> === Executable files ===<br /> Programs you can start are stored in executable files. They contain binary code directly understandable by the computer. They are files with an executable bit, a flag that shows AmigaOS that such file will do something when started.<br /> An example is a music player. When you start this executable, the player opens and you can start playing music files.<br /> <br /> AmigaOS can run two different kinds of executable files: the AmigaOS native programs made for the PowerPC processor and programs created for the Motorola 68k processors. The laters are executed inside an emulation that transcripts them into PowerPC code.<br /> <br /> ==== Scripts ====<br /> <br /> Scripts are text files containing a list of commands. So they are not strictly executables like ''binary code'' files but they can be executed by AmigaOS like if they were.<br /> This is the case with AmigaDOS and ARexx scripts. These files need to have the executable bit, and the script bit.<br /> <br /> === Data files ===<br /> Files that are not executable are data files. These contain some data that will be manipulated by programs. Some examples are a music file, a video file or a text document.<br /> <br /> == Directories/Drawers ==<br /> In order to organise things a bit, files are not all of them in the same place. We create directories which like drawers of a cabinet will store different files of the same kind.<br /> Often the name ''directory'' is used when talking about the directory which is stored on a disk. The graphical interface of AmigaOS being called the Workbench, directories are often called ''drawers''.<br /> <br /> Note: directories are often called ''folders'' on other systems.<br /> <br /> == Disks, partitions and volumes ==<br /> === Disks ===<br /> Disks are storage medium you can purchase on a computer store. We use them to store our files. They can be internal hard disks, external ones or a USB disk drive.<br /> <br /> === Partitions ===<br /> A disk is often very big and many users prefer to make it more organised. This is done virtually splitting the disk into several smaller parts. This operation is known as creating partitions on a disk.<br /> <br /> [[File:Partitions.png|Small part of Media Toolbox showing different partitions on the harddisk]]<br /> <br /> On this screenshot you can see one harddisk with many partitions. Each color corresponds to a different filesystem which defines how data is stored. Also you can see a greyed area which is a blank area on the disk i.e. no partition is defined at this position.<br /> <br /> === Volumes ===<br /> A partition is a physical area on a disk. To access it with AmigaOS we could read the physical data off the partition but it's not an easy way. To make it easier AmigaOS uses the concept of volumes. These are virtual representations of a partition. The volumes have a name so AmigaOS and therefore the user can access all files/directories stored on it in a very practical way: just by using its name.<br /> <br /> = How to identify files/directories =<br /> <br /> == On the Workbench ==<br /> <br /> The Workbench being graphical, a lot of things are understandable just by looking at them. That's why icons are often enough to understand what kind of object it represents: a file, a directory, a disk...<br /> <br /> In case you have a doubt, just look at the information on an icon. The Workbench will tell you the type of the object. It is displayed next to its name.<br /> <br /> == In a shell ==<br /> <br /> In a shell you need to issue the command '''list''' to see if an object is a file or a directory.<br /> <br /> [[File:Files-dirs-in-shell.png|The '''list''' command shows a file of 925678 bytes and two directories]]<br /> <br /> A file will be displayed with its size, whereas a directory will be displayed with the text '''Dir''' next to it.<br /> <br /> Also, as you can see on the screenshot, the list command displays other characteristics on these 3 items: the protection bits and the date they were updated the last time. The command also sums up what it just listed.<br /> <br /> = All AmigaOS components =<br /> <br /> AmigaOS is made of different components which have their own job in the system. The most important ones are mandatory. Without them the system does not even start. Other components are less important and the user can choose to use them or not. This is the case of drivers. For instance, a device driver may be omitted. If so, the corresponding device will just not work as AmigaOS will have no driver that allows it to know what to do with this device.<br /> <br /> == Kickstart modules ==<br /> <br /> These components are the heart of AmigaOS. Their duties is to do graphics, to handle discs or to handle all reads/writes to files. Also one of them is the AmigaOS kernel which is some kind of director handling the work of all other components.<br /> You can find all these modules in the '''Kickstart''' directory in the system volume. Here is a list:<br /> <br /> === Mandatory modules ===<br /> <br /> The following modules are required in any AmigaOS system. Without one of these, the system will not start.<br /> <br /> * kernel - The kernel works like a conductor in an orchestra. Its job is to make everything works together. It creates processes, handle memory usage, defines the way other components will access peripherals...etc. Note that the AmigaOS kernel is not based on any other kernel. It is a self made kernel that works since 1983.<br /> * loader - this component handles the loading of all other kickstart modules<br /> * battclock.resource.kmod - this module handles reading/writing the battery backed up clock which is used on all computers to keep the date and time<br /> * bootimage - this is the boot picture. It is displayed during the start sequence of AmigaOS<br /> * bootmenu.kmod - this component handles the Early Startup Menu the use can use to define some settings before starting AmigaOS<br /> * con-handler.kmod - it directs the read and write requests to the console window, to a serial AUX: device or any other supported interface<br /> * console.device.kmod - it opens a window and reads/writes text to and from that window<br /> * diskboot.kmod - handles the booting of AmigaOS from a supported disk<br /> * diskboot.config - this is a text file experienced users can modify to change the boot behaviour of AmigaOS<br /> * dos.library.kmod - this module is a collection of functions that any program can use to perform actions on disks, files and directories<br /> * elf.library.kmod - handles the loading of executable programs<br /> * env-handler.kmod - handles the read/writes of environment variables<br /> * FileSystem.resource.kmod - handles the use of the different filesystems<br /> * gadtools.library.kmod - collection of functions used to create all graphic objects like gadgets, sliders, menus...<br /> * gameport.device.kmod - handles the read/writes of game pads and joysticks<br /> * graphics.library.kmod - collection of functions used to draw graphic elements on the monitor<br /> * hunk.library.kmod - set of functions to read a data stream into memory<br /> * input.device.kmod - handles of input events like keyboard events or mouse clicks<br /> * intuition.library.kmod - collection of functions to create and handle all graphic elements (screens, windows, the mouse pointer...)<br /> * layers.library.kmod - set of functions to be used to handle different layers in graphic operations<br /> * keyboard.device.kmod - driver for the keyboard<br /> * keymap.library.kmod - functions to handle different keymaps<br /> * newlib.library.kmod - collection of functions to perform memory operations (allocating memory, copying memory areas... )<br /> * nonvolatile.library.kmod - provides a simple means for an application developer to manage nonvolatile storage<br /> * nvram.resource.kmod - handles the read/writes to the EEPROM chip present on many AmigaOS computers<br /> * PCIGraphics.card - driver that supports the use of different graphic cards<br /> * ram-handler.kmod - functions that handles the '''Ram disk:''' special disk<br /> * ramdrive.device.kmod - device that allows the usage of the ramdrive device '''RAD:''' disk<br /> * ramlib.kmod - loads disk based libraries and devices for exec.library<br /> * rtg.library - library of functions perform lowlevel graphic operations on graphic cards<br /> * shell.kmod - the AmigaOS command line interface<br /> * strap.kmod - module that handles booting on different disk devices<br /> * timer.device.kmod - driver to give access to timing functions<br /> <br /> === Filesystem support ===<br /> <br /> These kickstart modules can be loaded or left aside. If you want to use a particular filesystem on your disk partitions, you need to load the corresponding filesystem module.<br /> <br /> * CDFileSystem - handles the CD-ROM disks with data stored in different formats: ISO9660, HFS...<br /> * SmartFilesystem - allows to store data on partitions in SFS0 and SFS2<br /> * JXFileSystem - allows to create partitions in JXFS<br /> * FastFileSystem - allows the usage of partitions in FFS and FFS2 layouts<br /> * diskcache.library.kmod - component required by the SmartFileSystem and JXFileSystem modules<br /> <br /> === Hardware drivers ===<br /> <br /> ==== Graphic cards drivers ====<br /> <br /> * 3dfxVoodoo.chip<br /> * 3DLabsPermedia2.chip<br /> * ATIRadeon.chip<br /> * RadeonHD.chip<br /> * siliconmotion502.chip<br /> <br /> ==== Disk drivers ====<br /> <br /> Each of these drivers allow the use of disks connected to a disk controller. These files are named with the name of the controller they support. As an example, the '''sii3114ide.device.kmod''' allows to use disks connected on a '''Silicon Image SiI3114''' controller chip.<br /> <br /> * it8212ide.device.kmod<br /> * lsi53c8xx.device.kmod<br /> * sam460sata.device.kmod<br /> * sii3112ide.device.kmod<br /> * sii3512ide.device.kmod<br /> * sii3114ide.device.kmod<br /> * sii0680ide.device.kmod<br /> * sii3132ide.device.kmod<br /> <br /> ==== USB drivers ====<br /> <br /> * hub.usbfd<br /> * usbsys.device<br /> * usbresource.library<br /> * ehci.usbhcd<br /> * ohci.usbhcd<br /> * uhci.usbhcd<br /> * massstorage.usbfd<br /> <br /> ==== Other drivers ====<br /> <br /> * bootkeyboard.usbfd - allows a USB keyboard to be used even before the USB stack is loaded<br /> * bootmouse.usbfd - allows a USB mouse to be used even before the USB stack is loaded<br /> * fpga.resource.kmod - allows to use the FPGA components which are present on some Amiga computers<br /> * i2c.resource.kmod - allows to use the i2c interface present on some Amiga computers<br /> * xena.resource.kmod - provides access to the Xena chip on the AmigaOne X1000<br /> <br /> === Misc modules ===<br /> <br /> * petunia.library.kmod - this module contains the Just-In-Time emulator that allows AmigaOS to run programs made for the Motorola 68k processor<br /> <br /> == System components ==<br /> <br /> [[File:Workbench_directory_listing.png|frame|right|List of directories and files present at the root of any AmigaOS system]]<br /> <br /> Beside the kickstart modules, AmigaOS uses many different components that can be loaded only when used. These files are stored in different directories in the system volume.<br /> Here is described a default AmigaOS installation.<br /> <br /> * C<br /> This directory contains AmigaDOS '''C'''ommands<br /> * Classes<br /> contains different object elements easy to be used in any program: gadgets, requesters, graphic table, windows...<br /> * Devs<br /> contains definition for '''Dev'''ices<br /> * Emulation<br /> contains files used for the 68k emulation (though E-UAE)<br /> * Fonts<br /> contains various systems fonts<br /> * Internet<br /> contains a dialer to connect to Internet<br /> * Kickstart<br /> contains the kickstart modules<br /> * L<br /> contains hand'''l'''ers and filesystems<br /> * Libs<br /> contains dynamic '''Libr'''airies of functions<br /> * Locale<br /> contains all files used to localise the system (catalogs, keymaps...)<br /> * MUI<br /> contains the needed files for programs that use the MUI third party graphic interface<br /> * Prefs<br /> contains the preference programs used to customise AmigaOS<br /> * S<br /> contains the '''S'''cripts<br /> * SObjs<br /> contains .so shared object library files<br /> * Storage<br /> contains other optional files<br /> * System<br /> contains some programs used by the system itself (i.e. you don't need to run them yourself) or low-level programs like disk tools<br /> * Utilities<br /> contains several utilities<br /> <br /> = Motorola 680x0 Emulators =<br /> <br /> For a long time Amigas have had the famous Motorola 680x0 processors as the central unit for execution. Unfortunately the time of the 680x0 series is passing in favor of other architectures. The new era of processors reached the Amiga some time ago, when expansion boards became available for extending the Classic systems with the raw power of a PowerPC processor.<br /> <br /> In the old operating system (AmigaOS 3.x) it was not possible to gain the full advantage of the new processors. The system itself and most of the applications required the original Motorola 680x0 processor. There was no 680x0 emulation available for the PowerPCs, so the 680x0 could not be &quot;switched off&quot;.<br /> <br /> Thus the new processors remained as a powerful, but mostly unused adjunct to the main 680x0 processor. &quot;Native&quot; PowerPC programs were rare, and every time a PowerPC program called the system, a so called &quot;context switch&quot; occurred between the 680x0 and PowerPC code, often causing a large performance penalty.<br /> <br /> The new Amiga platform is based on the PowerPC processor family, therefore the new version of the AmigaOS has to smooth the transition from the 680x0 series, which is achieved by emulating the old processor architecture. The operating system itself is written almost 100 percent for the PowerPC processors, but the 680x0 legacy applications require an emulated 680x0 processor. <br /> <br /> == Two 680x0 Emulators ==<br /> <br /> In version 4.0 of AmigaOS, two different emulators were implemented; one is the successor of BlackBox emulation, it is an interpretive emulator, thus the emulation speed is mediocre. On the other hand it has a very low &quot;reaction time&quot;, and is ideal for time critical parts, such as interrupts.<br /> <br /> The other is Petunia, the &quot;JIT emulator&quot;. A fast, but less compatible way of emulation of the legacy Motorola processors. It is intended mainly for emulating applications, and therefore, when execution of the application leaves the bounds of the application's code segment, emulation falls back to the interpretive method, where it does its job and returns to the JIT emulation again.<br /> <br /> Dynamic recompilation (also called just-in-time compilation or simply JIT compilation) is a technique of translating foreign processor machine code to native machine code, &quot;on the fly&quot;.<br /> <br /> This technique is common nowadays, commonly applied in JAVA virtual machines, and it is also used with success in several emulators. In dynamic recompilation there is the possibility of runtime optimization of the emulated code by collecting statistics of the execution process. Therefore (theoretically) the final executed code can be even faster than the original code on its original processor.<br /> <br /> == Features ==<br /> <br /> Emulated opcodes:<br /> * all user and supervisor level opcodes of the Motorola 68040<br /> * all FPU opcodes of the Motorola 68881/68882 <br /> <br /> AmigaOS claims only 68020/68881 compatibility to applications because this is the safest compatibility level, but both emulators are compatible with the machine code up to the level of 68040/060 processors.<br /> <br /> At compile time, a low level flag and branch control analysis allows on-the-fly optimizations of compiled code.<br /> <br /> == Removing the JIT Emulator ==<br /> <br /> Using the dynamic translation requires a lot more memory than the interpretive emulation. The translated code needs to be stored somewhere, not to mention the data collection tables.<br /> <br /> If speed is not as important as the memory consumption of the system, then the JIT emulator can be removed, leaving the job to the interpretive emulator.<br /> <br /> Thanks to the modular design of AmigaOS kickstart, all you need to do is edit the &quot;Sys:Kickstart/Kicklayout&quot; file, simply put a semicolon (;) at the beginning of the module line of Petunia.library.kmod. After rebooting the system from cold, the JIT emulator will not be reloaded. Make sure that you alter the appropriate configuration in the Kicklayout file, there may be several alternative configurations, with different names like &quot;DefaultJIT&quot;, or &quot;DefaultNoJIT&quot;.<br /> <br /> == Configuring the Emulators ==<br /> <br /> Petunia cooperates with a so called &quot;black list&quot;. By default Petunia emulates every 680x0 program or library that is loaded by DOS.library/LoadSeg function, but if an executable or library shows incompatibilities with Petunia, then it can be explicitly inhibited from the dynamic recompilation by specifying it in a list file.<br /> <br /> If an executable needs to be added to the list, then it can be done by extending the file &quot;DEVS:applications.dos&quot; with the '''Compatibility''' preferences program from the Prefs drawer of the system. Adding a program name to the list and checking it will prevent Petunia from emulating that program, and it will be interpreted instead by the built-in interpreter.<br /> <br /> Removing a program from the list or unchecking (thus allowing Petunia to emulate it again) can be done with the same preferences program.<br /> <br /> Please note: some programs consist of multiple executables (shared libraries, plugins). If you want to fully disable the translation of such programs, then every part must be added to the list.<br /> <br /> For example to disable UnArc fully, you would have to add all files from libs:xad and also xadmaster.library to the list. <br /> <br /> = AmigaOS boot procedure =<br /> <br /> Basically a computer with AmigaOS does the following when the power button is pushed:<br /> <br /> * [[File:Uboot.jpg|200px]] the BIOS ([[UserDoc:BIOS|Uboot]] or [[UserDoc:BIOS|CFE]]) of the computer initialises the hardware: graphic card, USB ports... At this point, the monitor wakes up and the first information are displayed.<br /> * the BIOS looks on the harddisk and finds a file called the Second Level Booter (SLB). It is stored on the first sectors of the disk. Whereas the BIOS does not know about AmigaOS disk structure, the SLB will be able to ''understand'' the AmigaOS partitions and files.<br /> * [[File:SLB.png|200px]] the SLB will analyses all Amiga partitions and read each [[UserDoc:kickstart_configuration|system configuration]] it finds. It will show all available configurations for the user to select one to load.<br /> The user can define many different kickstart configurations to choose from. Also both AmigaOS and Linux can be selected for boot.<br /> * [[File:Kmods loading.png|200px]] the SLB loads the kickstart files of the selected configuration<br /> * SLB executes the '''Loader''' module<br /> * '''Loader''' executes the kickstart modules (Exec, devices, libraries...)<br /> * AmigaOS becomes alive displaying a boot picture on the monitor<br /> * the AmigaDOS library executes the [[UserDoc:System_Scripts#startup-sequence|startup-sequence]] script found on the system volume<br /> * the Startup-sequence will be executed and all commands it contains are executed. It means that starting from here the boot procedure is easy to follow and understand.<br /> * the Workbench is started<br /> <br /> At this point the user can use his/her computer.<br /> <br /> = How to make a Bootable USB Memory Stick for AmigaOS 4.1 =<br /> <br /> By Julian Margetson (&quot;Spectre660&quot;)<br /> <br /> Prerequisites:<br /> * USB memory stick of 2 GB or less in size.<br /> * It is best to only have one USB mass storage device connected while you are creating your bootable USB memory stick.<br /> * Plug the USB memory stick into a USB port on your machine.<br /> * Note that the device will be formatted so make sure that you use an empty memory stick or one that does not contain any data that you need or backup the contents before you begin.<br /> <br /> Procedure:<br /> # You use Media Toolbox in the System: drawer to prepare the USB stick. On starting Media Toolbox select ''usbdisk.device'' as the device to use.<br /> # Make certain that you have selected usbdisk.device and not any other device.<br /> # Click on &quot;Start&quot;<br /> # You will see the usb mass storage unit connected in a list.<br /> # Make sure that the Unit type displayed for the USB memory stick is &quot;Removable hard disk&quot;<br /> # Select that Unit by clicking on it.<br /> # The first thing that you need to do is to install the RDB onto the USB Memory Stick.<br /> # Click on the &quot;Install&quot; button.<br /> # A window Labeled &quot;RDB/disk geometry editing&quot; comes up.<br /> ## Towards the bottom of the window is the &quot;AmigaOne boot code (SLB)&quot; section.<br /> ## Select the &quot;Install&quot; button .<br /> ## A file requester &quot;Select AmigaOne Boot Code&quot; now comes up with the Drawer choice defaulting to &quot;l:&quot;<br /> ## Select file &quot;slb_v2&quot;. <br /> ## Select Ok.<br /> ## You are now returned to the &quot;RDB/disk geometry editing window&quot;.<br /> ## Select &quot;Ok-accept changes&quot;.<br /> # You are now returned to the display showing the attached USB unit.<br /> # Select &quot;Edit partitions and Filesystems&quot;. You will now see the Window 'Editing partitions for disk&quot;<br /> # Select &quot;Add partition&quot;<br /> # This defaults to using the whole device as a single partition.<br /> # It is possible to use create more partitions but for this tutorial we will only use one.<br /> # You now need to give the partition a unique name (e.g. USB0 or something that is different from any of the existing partitions on your hard drive). This is done by changing the default DH0 in the &quot;Name&quot; box.<br /> # Now make sure that the Boxes &quot;Automount&quot; and &quot;Bootable&quot; are selected and show the &quot;Tick mark&quot;.<br /> # You need to set &quot;Boot priority&quot; to higher than the boot priority of your hard drive boot partition(s). This is done by increasing Boot priority by clicking on the &quot;+&quot; to the right of the &quot;boot priority&quot; box. Normally you can set the boot priority to 2 .<br /> # Next it is time to select the file system to use.<br /> # Select &quot;Select filesystem/edit details&quot;.<br /> # The Window &quot;Editing details for partition 'USB0'&quot; ,or whatever partition name you used, comes up.<br /> ## Select the file system that you are going to use by selecting the pull down menu under &quot;Filesystem chooser&quot;.<br /> ## Only filesystems SFS/00 or SFS/02 will work for a bootable device.<br /> ## The option that gives the most flexibility at the moment is SFS/00 as a USB stick in this format can be read and written to using another compatible system in the event that you need to make modifications after it is created without a booting AmigaOS 4.1 machine.<br /> ## Next select Blocksize from the &quot;Blocksize&quot; pull down menu. 512 is the correct size to use.<br /> ## Now Select &quot;Ok-accept changes&quot;.<br /> ## Your are now returned to the &quot;Edit partitions for disk&quot; window.<br /> ## Again select &quot;Ok-accept changes&quot;<br /> # You are now returned to the window showing the USB mass storage unit list.<br /> # Select &quot;Save to disk&quot;<br /> # A requester pops up with the options &quot;Yes, Save.&quot; or &quot;No!&quot;<br /> # Select the &quot;Yes, save.&quot; option.<br /> # You now close Media Toolbox by clicking on the close icon (X) on the left of the Media Toolbox window.<br /> # This will give you a requester advising that you need to reboot the machine for the changes to take effect. At this point you need to remove the USB memory stick for the machine. If you do not then the Machine will attempt boot from it before it is formatted and the required Kickstart and AmigaOS 4.1 files are copied to it.<br /> # Select &quot;Yes, reboot NOW!&quot;.<br /> # Once you have rebooted connect your USB Memory Stick to a USB port.<br /> # A disk icon &quot;USB0:Uninitialized&quot; (or whatever partition name you used) appears on Workbench.<br /> # You now need to format the device.<br /> # To format Select this Icon and go to the Workbench &quot;Icons&quot; menu .<br /> # Select &quot;Format Disk&quot;<br /> # You can give the USB Memory Stick a unique name and select whether you want a Trashcan or not.<br /> # You can use either a full Format or a Quick Format. Full Format may take a few minutes.<br /> # Once formatted the USB Memory Stick is ready for you to copy the required files from you hard drive or AmigaOS Install CD to it in order to boot AmigaOS 4.1 from it.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=Installation_Utility&diff=6208 Installation Utility 2013-07-28T10:04:25Z <p>Philippe Ferrucci: /* AddPackage */</p> <hr /> <div>= How the installer works =<br /> <br /> == Basic concept ==<br /> <br /> The installation utility executes a python script that sets up the installation. In addition to standard Python commands the installation utility provides a module called &quot;installer&quot; and an interface to it. Using this interface you can create the different pages that can be found in almost all installation processes: a welcome page, a displayed licence page, a selection page, an installation page and finally a finish page.<br /> In the end, there are only a few script commands required.<br /> <br /> == Running an installation script ==<br /> <br /> === From the command line ===<br /> <br /> In order to run an installation from the command line, invoke the installation utility giving your script file as an argument and if you want a logo to be displayed at the top of the window:<br /> <br /> &lt;pre&gt;<br /> &quot;SYS:Utilities/Installation utility&quot; PACKAGE=myscript.py LOGO=mylogo.png<br /> &lt;/pre&gt;<br /> Note: the logo will be displayed all along the installation process.<br /> <br /> ''Note2: right now you need to set these argument names with capital letters, as shown above.''<br /> <br /> === From the Workbench ===<br /> <br /> Add a project icon to your script and use ''SYS:Utilities/Installation utility'' as the default tool.<br /> <br /> ==== Tooltypes ====<br /> <br /> * PACKAGE (Default: ''package.py'')<br /> <br /> This tooltype is used to specify the script name to execute. It is useful if you want to use a standalone icon that will open a script with a different name or in another directory.<br /> <br /> * LOGO<br /> <br /> You can use this tooltype to specify an image name to use in the installer window.<br /> <br /> = Example script =<br /> <br /> A minimal install script looks like this:<br /> <br /> &lt;pre&gt;<br /> # Simple, basic installation script<br /> from installer import *<br /> <br /> # These will be used for the first page (welcome) and last page (finish)<br /> welcomeText = &quot;This is a welcome text, displayed at the first page&quot;<br /> finishText = &quot;This is the finish message&quot;<br /> <br /> # Define the Welcome page<br /> welcomePage = NewPage(WELCOME)<br /> SetString(welcomePage, &quot;message&quot;, welcomeText)<br /> <br /> # Define the License page. The user must accept this license to continue the install process.<br /> # The license text will be read from a text file called &quot;license.txt&quot; and will be displayed on the page.<br /> licensePage = NewPage(LICENSE)<br /> <br /> # Define a page to select the installation directory<br /> destinationPage = NewPage(DESTINATION)<br /> SetString(destinationPage, &quot;message&quot;, &quot;Please indicate where you want to install the files .&quot;)<br /> SetString(destinationPage, &quot;destination&quot;, &quot;SYS:&quot;)<br /> <br /> # Define a selection page for the features to install<br /> packagePage = NewPage(PACKAGESELECT)<br /> <br /> # Define a progress page that is shown during the installation<br /> installPage = NewPage(INSTALL)<br /> <br /> # Create a &quot;finish&quot; page.<br /> finalPage = NewPage(FINISH)<br /> SetString(finalPage, &quot;message&quot;, finishText)<br /> <br /> # Finally, this runs the installation.<br /> RunInstaller()<br /> &lt;/pre&gt;<br /> <br /> = Python Interface =<br /> <br /> == Introduction ==<br /> <br /> The installer is entirely programmed in Python. For this purpose, it provides a Python module called 'installer' that serves as a functional interface to the GUI. The entire GUI is build out of pages. Pages present different kind of information to the user. The installation can be navigated with a pair of forward/backward buttons to visit each page in turn. Certain pages (notably the INSTALL page) will trigger the installation process itself, although the interface is flexible enough to make an installation that is entirely driven by the Python script. A minimal setup function will create a &quot;default&quot; layout of pages for an installer. The basic is to have a single archive that is installed into a destination drawer created on the disk - about 90% of all installers will do exactly this. Therefore a lot of the mechanics involved in this type of installer is automated.<br /> <br /> == Python Functions in the installer package ==<br /> <br /> === NewPage ===<br /> <br /> This function creates a new page and returns its page number for later reference. The only argument to the function is the type of page to create. Possible values are:<br /> <br /> ; WELCOME<br /> : A message page, usually used for displaying a &quot;welcome&quot; message, although other uses are perfectly possible as well.<br /> : ''Note:'' this page is mandatory.<br /> <br /> ; FINISH<br /> : A message page that is specifically targeted at closing the installation. This page automatically gets the &quot;finish&quot; attribute set to make the installation change the &quot;cancel&quot; to the &quot;finish&quot; button.<br /> <br /> ; DESTINATION<br /> : A page to select a directory to serve as the target for the installation.<br /> : ''Note:'' this page is mandatory.<br /> <br /> ; INSTALL<br /> : The presence of this page automatically triggers the installation of the selected packages.<br /> <br /> ; GUI<br /> : A page where GUI elements can be added and controlled via a Python handler.<br /> <br /> ; PROCESSING<br /> : A page to display a simple progress bar for doing some Python-scripted processing.<br /> <br /> ; LICENSE<br /> : A brickwall page that displays a license agreement that only lets the user continue after accepting the license.<br /> : ''Note:'' the installation utility will look for a text file called &quot;license_''languagename''.language.txt&quot;, if not found, it will look for a file called &quot;license.txt&quot;.<br /> <br /> ; README<br /> : A page that displays a text file from disk for reference/README purposes.<br /> <br /> If the page cannot be generated, an OSError exception is raised.<br /> <br /> === GotoPage ===<br /> <br /> This function accepts a single argument, the page to display. This function should rarely be needed.<br /> <br /> === SetString, SetInteger, SetObject ===<br /> <br /> This function sets a variable of the specified type on a page. It accepts three parameters:<br /> * # The Page number to set the variable on<br /> * # The name of the variable<br /> * # The variable content.<br /> <br /> === GetString, GetInteger, GetObject ===<br /> <br /> These functions are the reverse of the above - they read a variable from the page specified as its first argument and the name specified as the second argument. They return a default value if the name was not found.<br /> <br /> === RunInstaller ===<br /> <br /> This function runs the installer's main loop, and needs to be the last command in an installation. Any subsequent scripting is done via handlers connected to the pages.<br /> <br /> === AddPackage ===<br /> <br /> This function adds a package to the list of installable packages. The function's interface uses keywords to make it more readable. The keywords are<br /> <br /> ; type<br /> : The type of package. This can be either FILEPACKAGE, ARCHIVEPACKAGE or HANDLERPACKAGE. A file package copies a list of files to the destination. An archive package unpacks a list of archives at the destination. Finally, a handler package is an abstract package that executes a handler when it is installed or upon certain actions.<br /> : This argument MUST be given.<br /> <br /> ; name<br /> : A string that specifies the name of the package. This name is presented to the user of the installer on a PACKAGESELECT page.<br /> : A name should be given. It defaults to an empty string.<br /> <br /> ; description<br /> : A textual description of the package. It is presented to the user next to the package list on a PACKAGESELECT page if the package is selected in the package list.<br /> : The description may be empty, although it is consider bad style. It defaults to an empty string.<br /> <br /> ; optional<br /> : A boolean value indicating whether the package is optional to install or required to be installed. A value of True means the package is optional.<br /> : Default is True (package is optional)<br /> <br /> ; selected<br /> : A boolean indicating whether the package should be pre-selected or not. If True, the package is selected the first time the PACKAGESELECT page is entered.<br /> : Default is True (package is selected), although the user might deselect the package on a PACKAGESELECT page<br /> <br /> ; diskspace<br /> : An integer value specifying the number of bytes the package occupies after installation. If a zero size is given (or the parameter is omitted) the installer tries to figure out the size requirements automatically, but be warned this might be a time consuming process.<br /> : Defaults to zero (try to figure out yourself)<br /> <br /> ; featuregroup<br /> : An integer bitmask giving one bit of each feature group defined. A one bit indicates this package is part of the group, while a zero bit indicates it isn't.<br /> : Defaults to zero (not in any feature group)<br /> <br /> ; alternatepath<br /> : Specifies an alternative installation path. For example, some files might need to be installed into LIBS: instead of the usual destination. This feature should be used with care.<br /> : Defaults to None (i.e. no alternate path)<br /> <br /> ; files<br /> : A list of strings, each string representing one file associated with this package. The interpretation of these files depend on the package type:<br /> :: ARCHIVEPACKAGE: each file is an archive that is supposed to be extracted into the destination.<br /> :: HANDLERPACKAGE: The strings are not interpreted in any way, it is up to the handler to do that.<br /> :: FILEPACKAGE: Each string stands for a file or directory to be copied. Files are straight copies, while directory names are interpreted slightly different: if a directory name is given, that entire directory is copied to the destination, including the directory itself. For example, if you specify &quot;System&quot; then the destination directory will include a &quot;System&quot; directory. On the other hand, if you specify it as &quot;System/&quot; with a trailing slash, the content of the directory will be copied but not the directory itself, i.e. the destination directory would contain all the file and directories in the &quot;System&quot; directory but not the directory itself.<br /> :: ''Note:'' directory/file names must be relative to the current directory i.e. where the installer is executed. You cannot use here a complete path name with the volume name like ''RAM:mydir''.<br /> : The default is an empty list.<br /> <br /> The result of this function is a package number, which can be used subsequently to adjust package settings or query certain features.<br /> <br /> == GUI's ==<br /> <br /> GUI's must be created from scratch using a procedural interface. The following procedures deal with creating and handling the user interface. In general, the user interface must be generated once and cannot be changed afterwards (with exceptions, see below).<br /> <br /> A GUI is started with a call to StartGUI(page_number). This will start to create a GUI on the indicated page number, and all subsequent calls will add to this GUI until EndGUI() is called. If the indicated page number is invalid or is not a GUI page, ever subsequent calls are ignored until a new StartGUI with a valid page number is called.<br /> <br /> Immediately after the call, a single GUI object might be defined. In almost all cases, this will be a group to hold a number of GUI elements. Groups are defined with the BeginGroup and EndGroup calls.<br /> <br /> BeginGroup takes the following keyword arguments:<br /> ; orientation<br /> : This specifies whether the children of this group are laid out vertically or horizontally. By default the layout is vertically.<br /> ; label<br /> : A short text string that can be displayed as a label for this group. The label is only used if a frame other than NONE_FRAME is specified. By default no label is used.<br /> ; frame<br /> : One of the constants NONE_FRAME, THIN_FRAME, BUTTON_FRAME, GROUP_FRAME, FIELD_FRAME, DROPBOX_FRAME, SBAR_HORIZ_FRAME, SBAR_VERT_FRAME, BOX_FRAME, STANDARD_FRAME. They directly correspond to the bevel styles of bevel.image. Defaults to NONE_FRAME.<br /> ; weight<br /> : An integer defining the weighted width or height of this group. This corresponds to layout.gadget's CHILD_WeightedWidth or CHILD_WeightedHeight tags, depending on the layout direction.<br /> <br /> EndGroup has no parameters and automatically terminates the last group opened by BeginGroup.<br /> <br /> User interface elements are added with the following calls. All of these return an ID number.<br /> <br /> === AddLabel ===<br /> <br /> This call adds a text label, with selectable frame. The following keyword arguments are supported:<br /> ; label<br /> : A string that specifies the label to be displayed. Default is empty, although an empty label doesn't make much sense<br /> <br /> ; weight<br /> : The weight of the label, as explained above.<br /> <br /> ; frame<br /> : A frame to put around the label.<br /> <br /> === AddButton ===<br /> <br /> This call adds a push button object to the current group. The function supports the following keyword arguments:<br /> ; label<br /> : A string specifying the label to be displayed within the button. Defaults to an empty label.<br /> <br /> ; frame<br /> : One of the constants mentioned above for the group. Defaults to BUTTON_FRAME.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; onclick<br /> : A Python callable object that is invoked when the button is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id) where page_number is the page number of the GUI page and element_id is the element id returned by this call.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddCheckBox ===<br /> <br /> This call adds a checkbox object to the GUI. The following keyword arguments are valid:<br /> <br /> ; label<br /> : A string that appears as a label to the right of the checkbox. Defaults to an empty label.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; checked<br /> : An integer that specifies whether the checkbox is initially checked or not. A zero means the checkbox is clear, any other value says the box is checked.<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the checkbox is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, state) where page_number and element_id are the same as above, and state is a 0 if the user just unchecked the checkbox, or a 1 is it was just checked.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddRadioButton ===<br /> <br /> This call adds a set of mutually exclusive radio buttons. The following keyword arguments are valid:<br /> <br /> ; labels<br /> : A list of Python strings, with each of these strings appearing as a choice on the Radio buttons. This parameter is required.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; selected<br /> : The number of the button initially selected. Defaults to the first button (0).<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the radio button is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the button number that was selected.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddChooser ===<br /> <br /> This function adds a chooser gadget to the GUI. The following keyword arguments are valid:<br /> <br /> ; label<br /> : A test string to be displayed in the chooser in pop-up mode (see below). Defaults to an empty string, and is not used for drop-down mode.<br /> <br /> ; choices<br /> : A list of text strings to be displayed as choices for the chooser. This argument is mandatory.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; selected<br /> : The number of the currently visible item in drop-down mode. Defaults to 0.<br /> <br /> ; mode: One of the constants CHOOSER_POPUP or CHOOSER_DROPDOWN. This corresponds to the chooser.gadget CHOOSER_PopUp and CHOOSER_DropDown tag items.<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the chooser is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the title number that was selected.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddSpace ===<br /> <br /> This call adds a bit of space to the GUI. It accepts only one parameter:<br /> <br /> ; weight<br /> : An integer specifying the weight of the space. Defaults to 1.<br /> <br /> The call does not return a value. Space does not have any variables.<br /> <br /> == User Interface Settings ==<br /> <br /> In order to change some aspects of user interface elements (like the selection status of a checkbox) or read their current state, two functions exist called GetUIAttr and SetUIAttr.<br /> <br /> The former reads an attribute from an identified user interface element (identified by the page number and element id) while the latter sets (and updates the on-screen representation) of an equally identified element.<br /> <br /> A number of attributes can be set and gotten from UI elements; some of them are shared among more than one element type, while others are specific. The following list names the attributes:<br /> <br /> ; GUI_LABEL (string)<br /> : The label displayed on a UI element.<br /> : Applies to BUTTON, LABEL, GROUP, CHECKBOX<br /> <br /> ; GUI_SELECTED (integer)<br /> : The selected item in a chooser or radio button.<br /> : Applies to CHOOSER and RADIOBUTTON<br /> <br /> ; GUI_CHECKED (integer)<br /> : Whether the checkbox checkmark is set or not.<br /> : Applies to CHECKBOX<br /> <br /> ; GUI_ONCLICK (Python callable)<br /> : The handler invoked when the UI element is activated.<br /> : Applies to CHOOSER, BUTTON, LABEL, GROUP, CHECKBOX, RADIOBUTTON<br /> <br /> The GetUIAttr function's prototype looks like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> result = GetUIAttr(page_nr, id, attr)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> page_nr and id identify the object by giving the GUI's page number and the element id returned by the creation call. The attr parameter is one of the attributes given above. Valid parameters for attr are GUI_SELECTED, GUI_CHECKED and GUI_ONCLICK.<br /> <br /> For SetUIAttr, the prototype looks like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> SetUIAttr(page_nr, id, attr, value)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> page_nr and id and attr are the same as above. The value parameter specifies the new value of the attribute, and must match the type for the attribute or the call will have no effect.</div> Philippe Ferrucci https://wiki.amigaos.net/w/index.php?title=Installation_Utility&diff=6207 Installation Utility 2013-07-28T10:03:54Z <p>Philippe Ferrucci: /* AddPackage */</p> <hr /> <div>= How the installer works =<br /> <br /> == Basic concept ==<br /> <br /> The installation utility executes a python script that sets up the installation. In addition to standard Python commands the installation utility provides a module called &quot;installer&quot; and an interface to it. Using this interface you can create the different pages that can be found in almost all installation processes: a welcome page, a displayed licence page, a selection page, an installation page and finally a finish page.<br /> In the end, there are only a few script commands required.<br /> <br /> == Running an installation script ==<br /> <br /> === From the command line ===<br /> <br /> In order to run an installation from the command line, invoke the installation utility giving your script file as an argument and if you want a logo to be displayed at the top of the window:<br /> <br /> &lt;pre&gt;<br /> &quot;SYS:Utilities/Installation utility&quot; PACKAGE=myscript.py LOGO=mylogo.png<br /> &lt;/pre&gt;<br /> Note: the logo will be displayed all along the installation process.<br /> <br /> ''Note2: right now you need to set these argument names with capital letters, as shown above.''<br /> <br /> === From the Workbench ===<br /> <br /> Add a project icon to your script and use ''SYS:Utilities/Installation utility'' as the default tool.<br /> <br /> ==== Tooltypes ====<br /> <br /> * PACKAGE (Default: ''package.py'')<br /> <br /> This tooltype is used to specify the script name to execute. It is useful if you want to use a standalone icon that will open a script with a different name or in another directory.<br /> <br /> * LOGO<br /> <br /> You can use this tooltype to specify an image name to use in the installer window.<br /> <br /> = Example script =<br /> <br /> A minimal install script looks like this:<br /> <br /> &lt;pre&gt;<br /> # Simple, basic installation script<br /> from installer import *<br /> <br /> # These will be used for the first page (welcome) and last page (finish)<br /> welcomeText = &quot;This is a welcome text, displayed at the first page&quot;<br /> finishText = &quot;This is the finish message&quot;<br /> <br /> # Define the Welcome page<br /> welcomePage = NewPage(WELCOME)<br /> SetString(welcomePage, &quot;message&quot;, welcomeText)<br /> <br /> # Define the License page. The user must accept this license to continue the install process.<br /> # The license text will be read from a text file called &quot;license.txt&quot; and will be displayed on the page.<br /> licensePage = NewPage(LICENSE)<br /> <br /> # Define a page to select the installation directory<br /> destinationPage = NewPage(DESTINATION)<br /> SetString(destinationPage, &quot;message&quot;, &quot;Please indicate where you want to install the files .&quot;)<br /> SetString(destinationPage, &quot;destination&quot;, &quot;SYS:&quot;)<br /> <br /> # Define a selection page for the features to install<br /> packagePage = NewPage(PACKAGESELECT)<br /> <br /> # Define a progress page that is shown during the installation<br /> installPage = NewPage(INSTALL)<br /> <br /> # Create a &quot;finish&quot; page.<br /> finalPage = NewPage(FINISH)<br /> SetString(finalPage, &quot;message&quot;, finishText)<br /> <br /> # Finally, this runs the installation.<br /> RunInstaller()<br /> &lt;/pre&gt;<br /> <br /> = Python Interface =<br /> <br /> == Introduction ==<br /> <br /> The installer is entirely programmed in Python. For this purpose, it provides a Python module called 'installer' that serves as a functional interface to the GUI. The entire GUI is build out of pages. Pages present different kind of information to the user. The installation can be navigated with a pair of forward/backward buttons to visit each page in turn. Certain pages (notably the INSTALL page) will trigger the installation process itself, although the interface is flexible enough to make an installation that is entirely driven by the Python script. A minimal setup function will create a &quot;default&quot; layout of pages for an installer. The basic is to have a single archive that is installed into a destination drawer created on the disk - about 90% of all installers will do exactly this. Therefore a lot of the mechanics involved in this type of installer is automated.<br /> <br /> == Python Functions in the installer package ==<br /> <br /> === NewPage ===<br /> <br /> This function creates a new page and returns its page number for later reference. The only argument to the function is the type of page to create. Possible values are:<br /> <br /> ; WELCOME<br /> : A message page, usually used for displaying a &quot;welcome&quot; message, although other uses are perfectly possible as well.<br /> : ''Note:'' this page is mandatory.<br /> <br /> ; FINISH<br /> : A message page that is specifically targeted at closing the installation. This page automatically gets the &quot;finish&quot; attribute set to make the installation change the &quot;cancel&quot; to the &quot;finish&quot; button.<br /> <br /> ; DESTINATION<br /> : A page to select a directory to serve as the target for the installation.<br /> : ''Note:'' this page is mandatory.<br /> <br /> ; INSTALL<br /> : The presence of this page automatically triggers the installation of the selected packages.<br /> <br /> ; GUI<br /> : A page where GUI elements can be added and controlled via a Python handler.<br /> <br /> ; PROCESSING<br /> : A page to display a simple progress bar for doing some Python-scripted processing.<br /> <br /> ; LICENSE<br /> : A brickwall page that displays a license agreement that only lets the user continue after accepting the license.<br /> : ''Note:'' the installation utility will look for a text file called &quot;license_''languagename''.language.txt&quot;, if not found, it will look for a file called &quot;license.txt&quot;.<br /> <br /> ; README<br /> : A page that displays a text file from disk for reference/README purposes.<br /> <br /> If the page cannot be generated, an OSError exception is raised.<br /> <br /> === GotoPage ===<br /> <br /> This function accepts a single argument, the page to display. This function should rarely be needed.<br /> <br /> === SetString, SetInteger, SetObject ===<br /> <br /> This function sets a variable of the specified type on a page. It accepts three parameters:<br /> * # The Page number to set the variable on<br /> * # The name of the variable<br /> * # The variable content.<br /> <br /> === GetString, GetInteger, GetObject ===<br /> <br /> These functions are the reverse of the above - they read a variable from the page specified as its first argument and the name specified as the second argument. They return a default value if the name was not found.<br /> <br /> === RunInstaller ===<br /> <br /> This function runs the installer's main loop, and needs to be the last command in an installation. Any subsequent scripting is done via handlers connected to the pages.<br /> <br /> === AddPackage ===<br /> <br /> This function adds a package to the list of installable packages. The function's interface uses keywords to make it more readable. The keywords are<br /> <br /> ; type<br /> : The type of package. This can be either FILEPACKAGE, ARCHIVEPACKAGE or HANDLERPACKAGE. A file package copies a list of files to the destination. An archive package unpacks a list of archives at the destination. Finally, a handler package is an abstract package that executes a handler when it is installed or upon certain actions.<br /> : This argument MUST be given.<br /> <br /> ; name<br /> : A string that specifies the name of the package. This name is presented to the user of the installer on a PACKAGESELECT page.<br /> : A name should be given. It defaults to an empty string.<br /> <br /> ; description<br /> : A textual description of the package. It is presented to the user next to the package list on a PACKAGESELECT page if the package is selected in the package list.<br /> : The description may be empty, although it is consider bad style. It defaults to an empty string.<br /> <br /> ; optional<br /> : A boolean value indicating whether the package is optional to install or required to be installed. A value of True means the package is optional.<br /> : Default is True (package is optional)<br /> <br /> ; selected<br /> : A boolean indicating whether the package should be pre-selected or not. If True, the package is selected the first time the PACKAGESELECT page is entered.<br /> : Default is True (package is selected), although the user might deselect the package on a PACKAGESELECT page<br /> <br /> ; diskspace<br /> : An integer value specifying the number of bytes the package occupies after installation. If a zero size is given (or the parameter is omitted) the installer tries to figure out the size requirements automatically, but be warned this might be a time consuming process.<br /> : Defaults to zero (try to figure out yourself)<br /> <br /> ; featuregroup<br /> : An integer bitmask giving one bit of each feature group defined. A one bit indicates this package is part of the group, while a zero bit indicates it isn't.<br /> : Defaults to zero (not in any feature group)<br /> <br /> ; alternatepath<br /> : Specifies an alternative installation path. For example, some files might need to be installed into LIBS: instead of the usual destination. This feature should be used with care.<br /> : Defaults to None (i.e. no alternate path)<br /> <br /> ; files<br /> : A list of strings, each string representing one file associated with this package. The interpretation of these files depend on the package type:<br /> :: ARCHIVEPACKAGE: each file is an archive that is supposed to be extracted into the destination.<br /> :: HANDLERPACKAGE: The strings are not interpreted in any way, it is up to the handler to do that.<br /> :: FILEPACKAGE: Each string stands for a file or directory to be copied. Files are straight copies, while directory names are interpreted slightly different: if a directory name is given, that entire directory is copied to the destination, including the directory itself. For example, if you specify &quot;System&quot; then the destination directory will include a &quot;System&quot; directory. On the other hand, if you specify it as &quot;System/&quot; with a trailing slash, the content of the directory will be copied but not the directory itself, i.e. the destination directory would contain all the file and directories in the &quot;System&quot; directory but not the directory itself.<br /> :: ''Note:'' directory/file names must be relateive to the current directory i.e. where the installer is executed. You cannot use here a complete path name with the volume name like ''RAM:mydir''.<br /> : The default is an empty list.<br /> <br /> The result of this function is a package number, which can be used subsequently to adjust package settings or query certain features.<br /> <br /> == GUI's ==<br /> <br /> GUI's must be created from scratch using a procedural interface. The following procedures deal with creating and handling the user interface. In general, the user interface must be generated once and cannot be changed afterwards (with exceptions, see below).<br /> <br /> A GUI is started with a call to StartGUI(page_number). This will start to create a GUI on the indicated page number, and all subsequent calls will add to this GUI until EndGUI() is called. If the indicated page number is invalid or is not a GUI page, ever subsequent calls are ignored until a new StartGUI with a valid page number is called.<br /> <br /> Immediately after the call, a single GUI object might be defined. In almost all cases, this will be a group to hold a number of GUI elements. Groups are defined with the BeginGroup and EndGroup calls.<br /> <br /> BeginGroup takes the following keyword arguments:<br /> ; orientation<br /> : This specifies whether the children of this group are laid out vertically or horizontally. By default the layout is vertically.<br /> ; label<br /> : A short text string that can be displayed as a label for this group. The label is only used if a frame other than NONE_FRAME is specified. By default no label is used.<br /> ; frame<br /> : One of the constants NONE_FRAME, THIN_FRAME, BUTTON_FRAME, GROUP_FRAME, FIELD_FRAME, DROPBOX_FRAME, SBAR_HORIZ_FRAME, SBAR_VERT_FRAME, BOX_FRAME, STANDARD_FRAME. They directly correspond to the bevel styles of bevel.image. Defaults to NONE_FRAME.<br /> ; weight<br /> : An integer defining the weighted width or height of this group. This corresponds to layout.gadget's CHILD_WeightedWidth or CHILD_WeightedHeight tags, depending on the layout direction.<br /> <br /> EndGroup has no parameters and automatically terminates the last group opened by BeginGroup.<br /> <br /> User interface elements are added with the following calls. All of these return an ID number.<br /> <br /> === AddLabel ===<br /> <br /> This call adds a text label, with selectable frame. The following keyword arguments are supported:<br /> ; label<br /> : A string that specifies the label to be displayed. Default is empty, although an empty label doesn't make much sense<br /> <br /> ; weight<br /> : The weight of the label, as explained above.<br /> <br /> ; frame<br /> : A frame to put around the label.<br /> <br /> === AddButton ===<br /> <br /> This call adds a push button object to the current group. The function supports the following keyword arguments:<br /> ; label<br /> : A string specifying the label to be displayed within the button. Defaults to an empty label.<br /> <br /> ; frame<br /> : One of the constants mentioned above for the group. Defaults to BUTTON_FRAME.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; onclick<br /> : A Python callable object that is invoked when the button is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id) where page_number is the page number of the GUI page and element_id is the element id returned by this call.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddCheckBox ===<br /> <br /> This call adds a checkbox object to the GUI. The following keyword arguments are valid:<br /> <br /> ; label<br /> : A string that appears as a label to the right of the checkbox. Defaults to an empty label.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; checked<br /> : An integer that specifies whether the checkbox is initially checked or not. A zero means the checkbox is clear, any other value says the box is checked.<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the checkbox is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, state) where page_number and element_id are the same as above, and state is a 0 if the user just unchecked the checkbox, or a 1 is it was just checked.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddRadioButton ===<br /> <br /> This call adds a set of mutually exclusive radio buttons. The following keyword arguments are valid:<br /> <br /> ; labels<br /> : A list of Python strings, with each of these strings appearing as a choice on the Radio buttons. This parameter is required.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; selected<br /> : The number of the button initially selected. Defaults to the first button (0).<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the radio button is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the button number that was selected.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddChooser ===<br /> <br /> This function adds a chooser gadget to the GUI. The following keyword arguments are valid:<br /> <br /> ; label<br /> : A test string to be displayed in the chooser in pop-up mode (see below). Defaults to an empty string, and is not used for drop-down mode.<br /> <br /> ; choices<br /> : A list of text strings to be displayed as choices for the chooser. This argument is mandatory.<br /> <br /> ; weight<br /> : As above<br /> <br /> ; selected<br /> : The number of the currently visible item in drop-down mode. Defaults to 0.<br /> <br /> ; mode: One of the constants CHOOSER_POPUP or CHOOSER_DROPDOWN. This corresponds to the chooser.gadget CHOOSER_PopUp and CHOOSER_DropDown tag items.<br /> <br /> ; onclick<br /> : A python callable object that is invoked when the chooser is clicked. The call is made with the following parameters:<br /> :: handler(page_number, element_id, selected) where page_number and element_id are the same as above, and selected is the title number that was selected.<br /> <br /> The call returns an id that can be used to construct the variable name for handling attributes of this object.<br /> <br /> === AddSpace ===<br /> <br /> This call adds a bit of space to the GUI. It accepts only one parameter:<br /> <br /> ; weight<br /> : An integer specifying the weight of the space. Defaults to 1.<br /> <br /> The call does not return a value. Space does not have any variables.<br /> <br /> == User Interface Settings ==<br /> <br /> In order to change some aspects of user interface elements (like the selection status of a checkbox) or read their current state, two functions exist called GetUIAttr and SetUIAttr.<br /> <br /> The former reads an attribute from an identified user interface element (identified by the page number and element id) while the latter sets (and updates the on-screen representation) of an equally identified element.<br /> <br /> A number of attributes can be set and gotten from UI elements; some of them are shared among more than one element type, while others are specific. The following list names the attributes:<br /> <br /> ; GUI_LABEL (string)<br /> : The label displayed on a UI element.<br /> : Applies to BUTTON, LABEL, GROUP, CHECKBOX<br /> <br /> ; GUI_SELECTED (integer)<br /> : The selected item in a chooser or radio button.<br /> : Applies to CHOOSER and RADIOBUTTON<br /> <br /> ; GUI_CHECKED (integer)<br /> : Whether the checkbox checkmark is set or not.<br /> : Applies to CHECKBOX<br /> <br /> ; GUI_ONCLICK (Python callable)<br /> : The handler invoked when the UI element is activated.<br /> : Applies to CHOOSER, BUTTON, LABEL, GROUP, CHECKBOX, RADIOBUTTON<br /> <br /> The GetUIAttr function's prototype looks like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> result = GetUIAttr(page_nr, id, attr)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> page_nr and id identify the object by giving the GUI's page number and the element id returned by the creation call. The attr parameter is one of the attributes given above. Valid parameters for attr are GUI_SELECTED, GUI_CHECKED and GUI_ONCLICK.<br /> <br /> For SetUIAttr, the prototype looks like this:<br /> <br /> &lt;syntaxhighlight&gt;<br /> SetUIAttr(page_nr, id, attr, value)<br /> &lt;/syntaxhighlight&gt;<br /> <br /> page_nr and id and attr are the same as above. The value parameter specifies the new value of the attribute, and must match the type for the attribute or the call will have no effect.</div> Philippe Ferrucci