1999-03-02 Emil Brink Defining a command 1. INTRODUCTION This little text describes how to define a new command in gentoo. Such a command is commonly referred to as a "user command". There are two kinds of commands in gentoo; those that are built-in ("native"), and those that aren't. The latter are what this text is about. In a perfect world, this file wouldn't exist, since this would all be covered in the Complete Gentoo Documentation. Unfortunately, that have yet to be written. In the meantime, perhaps this text can shed some light on the topic. Defining your own commands to do the things you want is an important part of utilizing gentoo, so this could be important stuff. Read on, and don't hesitate to mail me (at <emil@obsession.se>) if you have questions, corrections, or whatever. 2. WHERE IS IT DONE? To create a user command, open up gentoo's configuration dialog window, and click on the tab labeled "Commands". This displays a list of all currently defined user commands, plus interface controls that allow you to modify, add and delete commands. All operations described below refer to the current command. To make a command current, click on its name in the command listing. As the command becomes current, the interface reflects this by showing the settings for it. It will probably be a lot easier to follow this text if you open up the relevant window, so you can check out the interface along with reading about it... 3. WHAT'S A COMMAND? A user command has basically two parts: a name and a definition. The name is just some word you choose; typically it should be descriptive so you can understand what the command does from its name. Command names should begin with a lower-case letter, to distinguish them from the built-ins. The definition of a user command consists of a sequence of rows. Each row has a type; its either "built-in" or "external". In the former case, all the row does is envoke one of gentoo's built-in commands. In the latter case, the row causes an external program (such as a shell command or another application) to execute. 4. DEFINITION EDITING In the frame labeled "Definition", the current command's definition is shown. The main part of the frame is taken up by a list, showing the command's rows. To the left of the list are buttons for adding, duplicating, moving and deleting rows. These buttons all act on the current row; to make a row current just click it in the list. 4.1 ROW EDITING Once a row has been selected, you can modify it in various ways. These modifications are carried out through the interface below the row list. You can change a row's type, its contents, and the flags from this interface. 4.2 ROW TYPE To change a row's type, select the row and then locate the big popup- menu-button (or GtkOptionMenu as its known in the GTK+ widget set) in the top left corner of the row editing interface. It will read as either "Built-in" or "External", showing you the row's current type. Click on the button, and a popup-menu appears with these two types in it. Point at the desired type, and click again. The row's type changes to the one selected. 4.3 ROW DEFINITION STRING The most important part of a row is its definition string. This is a line of text that you can enter and edit in order to control what the row should do when executed. The meaning of the definition string is type-dependant. 4.3.1 BUILT-IN DEFINITION For a row of type "Built-In", the definition string is really simple: it's just the name of a gentoo built-in command to run. For example, you could enter "Quit" to envoke the quitting command. The tiny button labeled "..." to the right of the string entry field pops up a window allowing you to pick a command name from a list of built-ins. The name you select will replace whatever is in the entry box. 4.3.2 EXTERNAL DEFINITION The definition of an external command is a lot more flexible and power- ful than that for built-ins. As a side effect, it is also considerably more complex. Basically, what you want to do in a external row definition is tell gentoo which external command to run, and with which arguments. You can use special selection codes (spelled using braces) in the definition string to make gentoo supply information that you want to include in the execution. As a simple example, you could use a definition of "echo {f}" (without the quotes) to print out the name of the first selected item in the pane that is active when the command is run. In this example, 'echo' is the name of the standard shell command to print text; '{f}' is a info selection code that is replaced by the name of the first selected file. There are plenty of these data selection codes available. For a list (with brief explanations), click on the "..."-button located to the right of the entry field. The code you select will be appended at the end of the current definition. 4.3.3 EXTERNAL FLAGS External commands have a number of flags, that control their behaviour. There are three categories of flags: General, Before and After. The General flags control general aspects of the command exe- cution. The currently available flags are: Run in Background? Starts up the command in the background, letting it run without tying up gentoo's interface (as it otherwise would). Kill Previous Instance? Instructs gentoo to kill the process that the last execution of this command resulted in. Requires background execution. Survive Quit? Normally, gentoo will attempt to kill all child processes spawned from it when you quit. If this flag is set, the corre- sponding process will not be killed. Requires background. Capture Output? When this is set, gentoo will open up a window into which the command's standard output and error streams will be directed. The Before and After flag categories contain flags that are applied either before or after the command has executed. It works like this: first, the Before flags are applied. Then the child process that is going to run the command is spawned. When the child terminates, the After flags are applied. The flags available in the two categories are the same, with the exception of the "Change Directory" group, which is missing for obvious reasons in the After category. 5. NOTES Here are a few notes and general "words of wisdom" regarding user commands, their definition & execution: * The order in which rows are executed is unknown for rows that have the "Run in Background?" flag set. * Rows that don't run in the background must complete before the next row starts to execute. This means that you the sequence of rows really is a sequence; commands further down will run after those closer to the top, and thus can depend on their results. * External rows are executed by the execvp(3) system call, which means that you don't need to include paths in the command name. It also means that all the stuff normally done by the shell is missing (e.g. $- & ~-expansion, pipes, redirection with < & >). Dollar and tildeexpansion are provided through {}-codes. If you need pipes and/or redirection, run your program through the shell (e.g. use a string of 'sh "my_program <input >output | prog2"', where the single quotes should not be included, but the double ones should). * If a {}-code is likely to result in a string containing spaces, you may want to surround it with quotes in the command definition. * It is never necessary to define a user command containing just a single row of type "Built-In", since wherever a user command name is accepted, you can always enter the name of a built-in directly. This is how most of the example config's buttons work.