Differences
This shows you the differences between two versions of the page.
|
tutorial [2010/01/20 19:03] Drew Ames |
tutorial [2010/01/30 02:51] (current) Gilbert Ashley |
||
|---|---|---|---|
| Line 17: | Line 17: | ||
| **Step 1** | **Step 1** | ||
| - | Create a new empty directory anywhere on your system where you have read and write permissions. This can be in your HOME directory or nearly anywhere else except you shouldn't do this inside regular 'system' directories. src2pkg will refuse to run if you are trying to use it from someplace it considers 'wrong' or dangerous. | + | Create a new empty directory anywhere on your system where you have read and write permissions. This can be in your HOME directory or nearly anywhere else except you shouldn't do this inside regular 'system' directories. src2pkg will refuse to run if you are trying to use it from some place it considers 'wrong' or dangerous. |
| In the case of this example we'll work in our $HOME directory, so create the directory 'di' with such a command: | In the case of this example we'll work in our $HOME directory, so create the directory 'di' with such a command: | ||
| Line 31: | Line 31: | ||
| ''cd $HOME/di'' | ''cd $HOME/di'' | ||
| - | or navigate to that location with your file manager if using a GUI inetrface. If using a GUI, open a terminal-emulator program there -usually this is done by right clicking on the filer-manager window and choosing an option named something like 'Open a terminal here'. | + | or navigate to that location with your file manager if using a GUI inetrface. If using a GUI, open a terminal-emulator program there -usually this is done by right clicking on the filer-manager window and choosing an option named something like 'Open a terminal here' or 'xterm here'. |
| **Step 3** | **Step 3** | ||
| Line 59: | Line 59: | ||
| "Configuring sources using:" | "Configuring sources using:" | ||
| - | followed by a line which shows the configuration options used to compile the program. Notice that the --prefix option has been automatically filled-in for you. By default, src2pkg will use --prefix=/usr as we believe that 'best practices' almost always install *packaged* sfotware under /usr. But, you can change this by passing the -p=?? or --prefix option to src2pkg: | + | followed by a line which shows the configuration options used to compile the program. Notice that the --prefix option has been automatically filled-in for you. By default, src2pkg will use --prefix=/usr as we believe that 'best practices' almost always install *packaged* software under /usr. But, you can change this by passing the -p=?? or --prefix option to src2pkg: |
| ''src2pkg -CWD -p='/usr/local' di-3.11.tar.bz2'' | ''src2pkg -CWD -p='/usr/local' di-3.11.tar.bz2'' | ||
| Line 89: | Line 89: | ||
| 1. When run with the '-N' option, src2pkg will simply produce a basic build script with the name NAME.src2pkg.auto, where NAME is the name of the software package to be built. The command: ''src2pkg -CWD -N di-3.11.tar.bz2'' will produce a src2pkg build script named 'di.src2pkg.auto' (see explanation of '*.src2pkg.auto' files below) It will also produce a generic description file for the package, name 'new.slack-desc' (see explanation of 'new.*' files below). | 1. When run with the '-N' option, src2pkg will simply produce a basic build script with the name NAME.src2pkg.auto, where NAME is the name of the software package to be built. The command: ''src2pkg -CWD -N di-3.11.tar.bz2'' will produce a src2pkg build script named 'di.src2pkg.auto' (see explanation of '*.src2pkg.auto' files below) It will also produce a generic description file for the package, name 'new.slack-desc' (see explanation of 'new.*' files below). | ||
| - | 2. When run with the '-A' option, src2pkg tries to compile the sources and build the package first -and then writes the build script just before finishing the package. IN some cases this will produce a more complete build script than using the '-N' option because src2pkg has a chance to find out more about the sources since it de-compresses and (tries to) build them. But, no script will be written if the build fails. Actually, you can use the '-A' option after starting with the '-N' option and src2pkg will update the script if needed. Using the -A (AUTO_SCRIPT) option also turns on various internal functions which create any extra files needed for the package, and then copies these files to the current directory -with the same name as the 'real' file inside the package, but with a 'new.' prefix. | + | 2. When run with the '-A' option, src2pkg tries to compile the sources and build the package first -and then writes the build script just before finishing the package. In some cases this will produce a more complete build script than using the '-N' option because src2pkg has a chance to find out more about the sources since it de-compresses and (tries to) build them. But, no script will be written if the build fails. Actually, you can use the '-A' option after starting with the '-N' option and src2pkg will update the script if needed. Using the -A (AUTO_SCRIPT) option also turns on various internal functions which create any extra files needed for the package, and then copies these files to the current directory -with the same name as the 'real' file inside the package, but with a 'new.' prefix. |
| <blockquote>* Note: Explanation of 'new.*' and '*.src2pkg.auto' files | <blockquote>* Note: Explanation of 'new.*' and '*.src2pkg.auto' files | ||
| - | If you repeatedly run src2pkg using the -N and/or -A options, files with the 'new.' prefix and/or src2pkg build scripts with the name: NAME.src2pkg.auto will be generated each time, overwriting existing ones. The 'new.*' files have the same name as the file which was included inside the package -except for the 'new.' prefix. The -A option causes these files to be copied to the current directory so you can edit them if needed or wanted. But, you must change the name of the file to remove the 'new.' prefix. This tells src2pkg to use that file without changes and to not generate a new one. The main 'new.*' files which may be created by the -N option are the new.slack-desc and new.doinst.sh files (when creating Slackware-type packages). | + | If you repeatedly run src2pkg using the -N and/or -A options, files with the 'new.' prefix and/or src2pkg build scripts with the name: NAME.src2pkg.auto will be generated each time, overwriting existing ones. The 'new.*' files have the same name as the file which was included inside the package -except for the 'new.' prefix. The -A option causes these files to be copied to the current directory so you can edit them if needed or wanted. But, to make them be used and to be permanent you must change the name of the file to remove the 'new.' prefix. This tells src2pkg to use that file without changes and to not generate a new one. The main 'new.*' files which may be created by the -N option are the new.slack-desc and new.doinst.sh files (when creating Slackware-type packages). |
| Similarly, the file NAME.src2pkg.auto will be re-created each time until you change the name of it to drop the '.auto' suffix. Again, this tells src2pkg to not 'clobber' it any more and not change it. Be sure to change the name before you start editing it if needed or wanted. Still, remember that src2pkg will *edit* the file, if needed, if you first generated it with -N and then have src2pkg execute it with the -A option added.</blockquote> | Similarly, the file NAME.src2pkg.auto will be re-created each time until you change the name of it to drop the '.auto' suffix. Again, this tells src2pkg to not 'clobber' it any more and not change it. Be sure to change the name before you start editing it if needed or wanted. Still, remember that src2pkg will *edit* the file, if needed, if you first generated it with -N and then have src2pkg execute it with the -A option added.</blockquote> | ||
| Line 111: | Line 111: | ||
| All the lowercase options available from the command-line can be easily written into your scripts this way. This makes it really easy to keep a record of what options were used to create the package. And the 'record' is also a brief 'recipe' for re-creating the package as many times as needed or wanted, simply by running ''src2pkg -CWD -X'' | All the lowercase options available from the command-line can be easily written into your scripts this way. This makes it really easy to keep a record of what options were used to create the package. And the 'record' is also a brief 'recipe' for re-creating the package as many times as needed or wanted, simply by running ''src2pkg -CWD -X'' | ||
| - | Even though src2pkg provides a large number of command-line options, they are not nearly all the options available. Any of the other internal options can be easily used in your scripts. The syntax is similar to that of EXTRA_CONFIGS. That is most internal options or features use CAPITAL letters which describe what the option does. There are many such options available -so many that I won't try to outline them in this short tutorial. You can find out about many of them by looking through the file /usr/libexec/src2pkg/DEFINES. This file is used to set up default behaviours when they are not already given elsewhere (as in your *.src2pkg script). It is worth mentioning, that all of these options can also be passed to src2pkg as 'environmental variables': | + | Even though src2pkg provides a large number of command-line options, they are not nearly all the options available. Any of the other internal options can be easily used in your scripts. The syntax is similar to that of EXTRA_CONFIGS. That is, most internal options or features use CAPITAL letters which describe what the option does. There are many such options available -so many that I won't try to outline them in this short tutorial. You can find out about many of them by looking through the file /usr/libexec/src2pkg/DEFINES. This file is used to set up default behaviours when they are not already given elsewhere (as in your *.src2pkg script). It is worth mentioning, that all of these options can also be passed to src2pkg as 'environmental variables': |
| ''EXTRA_CONFIGS="--disable-cruft" src2pkg -e='--disable-cruft' di-3.11.tar.bz2'' | ''EXTRA_CONFIGS="--disable-cruft" src2pkg -e='--disable-cruft' di-3.11.tar.bz2'' | ||
| Line 119: | Line 119: | ||
| ''src2pkg -e='--disable-cruft' di-3.11.tar.bz2'' | ''src2pkg -e='--disable-cruft' di-3.11.tar.bz2'' | ||
| - | This measn that it easy to get src2pkg to 'play nice' with other scripts. For instance a very short script can be written which will build a whole 'tree' full of subdirectories with sources and build scripts with code like this: | + | This means that it is easy to get src2pkg to 'play nice' with other scripts. For instance a very short script can be written which will build a whole 'tree' full of subdirectories with sources and build scripts with code like this: |
| ''for dir in $(ls -1) , do'' | ''for dir in $(ls -1) , do'' | ||
| Line 127: | Line 127: | ||
| ''done'' | ''done'' | ||
| - | Even with all the things src2pkg 'knows' how to do, there will always be cases where src2pkg doesn't know how to build certain sources, or you simply want it to do something different than what it 'knows' to do -- maybe you want to add extra files to the package, remove files or even build extra sources and install them in the same package 'tree'. For these cases, src2pkg still provides an easy and reliable method for creating such build scripts. Nearly all the build 'instructions' which are part of the src2pkg API can be skipped by simply commenting them out in the script. the only one you should never skip is the first step 'pre_process'. | + | Even with all the things src2pkg 'knows' how to do, there will always be cases where src2pkg doesn't know how to build certain sources, or you simply want it to do something different than what it 'knows' to do -- maybe you want to add extra files to the package, remove files or even build extra sources and install them in the same package 'tree'. For these cases, src2pkg still provides an easy and reliable method for creating such build scripts. Nearly all the build 'instructions' which are part of the src2pkg API can be skipped by simply commenting them out in the script. The only one you should never skip is the first step 'pre_process'. |
| To get a better idea of what we are talking about, open the example script which you created above using src2pkg -- or create one now with this command: | To get a better idea of what we are talking about, open the example script which you created above using src2pkg -- or create one now with this command: | ||
| Line 133: | Line 133: | ||
| ''src2pkg -N di-3.11.tar.bz2'' | ''src2pkg -N di-3.11.tar.bz2'' | ||
| - | Any basic src2pkg such as the script di.src2pkg.auto has only about 50 lines and half of those are comments. The format is very clean and simple so that you can easily see, at a glance, any changes that you make to the script. At first, the only thing different between this example script and any other is in the lines which begin with SOURCE_NAME, NAME and VERSION. Lines which begin with the '#' character are comments and not executed when the script is run. There are a couple of other lines near the top which are uncommented, but less important -- like ''BUILD=1'' and ''PRE_FIX=/usr''. Scroll down further to see the real 'meat' of the script. At about line 20 there is an essential line like this: | + | Any basic src2pkg such as the script di.src2pkg.auto has only about 50 lines and half of those are comments. The format is very clean and simple so that you can easily see, at a glance, any changes that you make to the script. At first, the only thing different between this example script and any other is in the lines which begin with SOURCE_NAME, NAME and VERSION. Lines which begin with the '#' character are comments and are ignored when the script is run. There are a couple of other lines near the top which are commented and contain defaults -- like ''# BUILD=1'' and ''# PRE_FIX=/usr''. Scroll down further to see the real 'meat' of the script. At about line 20 there is an essential line like this: |
| ''. /usr/libexec/src2pkg/FUNCTIONS'' | ''. /usr/libexec/src2pkg/FUNCTIONS'' | ||
| Line 143: | Line 143: | ||
| What follows is the list of 16 instructions which are the basis of the src2pkg 'API'. Each instruction is actually a shell 'function'. A function is simply a block of code with a name. When the file /usr/libexec/src2pkg/FUNCTIONS gets 'sourced', all the functions are read into memory, but are only executed when they are called by name -as in the list inside the script. | What follows is the list of 16 instructions which are the basis of the src2pkg 'API'. Each instruction is actually a shell 'function'. A function is simply a block of code with a name. When the file /usr/libexec/src2pkg/FUNCTIONS gets 'sourced', all the functions are read into memory, but are only executed when they are called by name -as in the list inside the script. | ||
| - | Customizing a script is really simple. If one of the functions doesn't do what you need it to, you simply comment it out by placing a '#' character at the beginning of the line. And, if you need to carry out extra steps, like adding an extra file to the package, you simply insert a line or two of code between the regular functions at the correct spot. src2pkg makes this so easy that even people who don't know a thing about coding bash scripts cane a easily learn to customize the scripts. The syntax used is nearly exactly the same as what you'd use to perform the operation from the command-line -- following what you already know how to do, or following directions someone might give you on a forum, for instance. | + | Customizing a script is really simple. If one of the functions doesn't do what you need it to, you simply comment it out by placing a '#' character at the beginning of the line. And, if you need to carry out extra steps, like adding an extra file to the package, you simply insert a line or two of code between the regular functions at the correct spot. src2pkg makes this so easy that even people who don't know a thing about coding bash scripts cane a easily learn to customize the scripts. The syntax used is nearly exactly the same as what you'd use to perform the operation from the command-line -- following what you already know how to do, or following the directions someone might give you on a forum, for instance. |
| Internally, src2pkg uses variables for all locations, so you don't even have to code (or know) where the sources have been unpacked or where the package 'tree' is. Let's clarify these terms a little. Normally, there are really only three locations you need to be aware of. | Internally, src2pkg uses variables for all locations, so you don't even have to code (or know) where the sources have been unpacked or where the package 'tree' is. Let's clarify these terms a little. Normally, there are really only three locations you need to be aware of. | ||
| Line 149: | Line 149: | ||
| 1. The first is the 'current working directory' -- that is the location where you are runing src2pkg from -the same place where the NAME.src2pkg script is located. This is abbreviated in the scripts like this: "$CWD" | 1. The first is the 'current working directory' -- that is the location where you are runing src2pkg from -the same place where the NAME.src2pkg script is located. This is abbreviated in the scripts like this: "$CWD" | ||
| - | 2. The second location to be aware of is the location where the sources have been unpacked before configuring and compiling them. This is called "$SRC_DIR" which means 'source directory'. The actual location where sources get unpacked is configurable by editing the file /etc/src2pkg/src2pkg.conf. By default, sources get unpacked under the /tmp directory, but $SRC_DIR includes the full path to the sources for *just these sources*. So, in the case of our example, if you write this line in your script(anywhere below the pre_process function): echo "Sources are in $SRC_DIR" when the script is run it will show this: "Sources are in /tmp/di-3.11-src-1" (or "Sources are in /path/to/SRC_DIR"). The name is composed of the main path /tmp (or CWD), plus the NAME and VERSION of the sources. The 'src' part is to distinguish the name from any other directories found there -including the package tree. The last part '1' is the BUILD (release) number for the package. | + | 2. The second location to be aware of is the location where the sources have been unpacked before configuring and compiling them. This is called "$SRC_DIR" which means 'source directory'. The actual location where sources get unpacked is configurable by editing the file /etc/src2pkg/src2pkg.conf. By default, sources get unpacked under the /tmp directory, but $SRC_DIR includes the full path to the sources for *just these sources*. So, in the case of our example, if you write this line in your script (anywhere below the pre_process function): echo "Sources are in $SRC_DIR" when the script is run it will show this: "Sources are in /tmp/di-3.11-src-1" (or "Sources are in /path/to/SRC_DIR"). The name is composed of the main path /tmp (or CWD), plus the NAME and VERSION of the sources. The 'src' part is to distinguish the name from any other directories found there -including the package tree. The last part '1' is the BUILD (release) number for the package. |
| - | 3. the third location to be aware of is the 'package tree' which has been mentioned several times. This is a temporary location where the various files which will be included in the final package get assembled. Once all the package content is in the 'package tree', the contents are compressed into the final installable package. Again, the package tree is represented by a variable, called $PKG_DIR. And again this location can be configured. | + | 3. The third location to be aware of is the 'package tree' which has been mentioned several times. This is a temporary location where the various files which will be included in the final package get assembled. Once all the package content is in the 'package tree', the contents are compressed into the final installable package. Again, the package tree is represented by a variable, called $PKG_DIR. And again this location can be configured. |
| But from within your scripts you never have to refer to the absolute (real) location of these directories -you simply use the variable names and bash substitutes the real location -wherever that is at the time. This is handy because it means you don't have to edit your script in order to use it from anywhere on your system -- even after changing the default locations where sources get unpacked or packages get assembled. It also means you can share your scripts with others and they will also be able to use them without having to edit all the paths. | But from within your scripts you never have to refer to the absolute (real) location of these directories -you simply use the variable names and bash substitutes the real location -wherever that is at the time. This is handy because it means you don't have to edit your script in order to use it from anywhere on your system -- even after changing the default locations where sources get unpacked or packages get assembled. It also means you can share your scripts with others and they will also be able to use them without having to edit all the paths. | ||
tutorial.txt · Last modified: 2010/01/30 02:51 by Gilbert Ashley
