diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/CHANGELOG | 781 | ||||
| -rw-r--r-- | doc/COPYING | 340 | ||||
| -rw-r--r-- | doc/TODO | 5 | ||||
| -rw-r--r-- | doc/mkbuild-pt_BR.tex | 854 | ||||
| -rw-r--r-- | doc/simplaret-en.tex | 312 | ||||
| -rw-r--r-- | doc/simplaret-pt_BR.tex | 376 | ||||
| -rw-r--r-- | doc/simplepkg-en.tex | 390 | ||||
| -rw-r--r-- | doc/simplepkg-pt_BR.tex | 397 |
8 files changed, 3455 insertions, 0 deletions
diff --git a/doc/CHANGELOG b/doc/CHANGELOG new file mode 100644 index 0000000..68cecf2 --- /dev/null +++ b/doc/CHANGELOG @@ -0,0 +1,781 @@ +simplepkg changelog +=================== + +current +======= + + - new mkbuild sections acting as hooks: + - pre_configure + - configure + - pre_make_package + - make_package + - pre_install_package + - install_package + - post_install_package + +0.6 +=== + + - repos script moved to utils/ folder + - new "compact" template storage format + - common.sh: + - default arch when its not present at /etc/slackware-version is now assumed to be "i486" + - other minor changes and new functions + - repository metainformationg is now added at svn control if applicable + - new functions svn_remove_empty_folders, svn_del, su_svn, chown_svn, chgrp_svn, + regexp_slash, default_distro and svn_add + - new config parameter "TMP" + - renamed function use_svn to templates_under_svn + - simplaret: + - support for HTTPS + - simplaret_search_and_process_patch do not donwload a package with the same + package name twice in any case + - simplaret_set_arch: mapping non-present architectures to i486 + - default simplepkg.conf and repos.conf moved to defaults/ folder + - templatepkg and mkjail: minor changes + - templates: + - removed slackware and added slackware-12.1, slackware-12.2 + - added slamd64-11.0, slamd64-12.0 and slamd64-12.1 templates + - repos.conf and simplepkg.conf: + - default configuration making createpkg repository integrated with simplaret + - new repositories + - mkbuild: + - added --edit command line options, among others + - code cleanup + - all previous "commit" functions and command line options changed to "submit" as they + don't really commit files into the svn repository + - function svn_mkdir moved to common.sh + - function svn_add moved to common.sh and renamed as svn_copy + - some svn check routines extended for git + - perl.mkSlackBuild + - added sections copy_init_scripts and copy_config_files + - generic.mkSlackBuild, perl.mkSlackBuild and kde4.mkSlackBuild + - clean_builds now compliant with standard --cleanup behaviour + - new section slack-required, download_patches, manifest_check + - generic.mkSlackBuild: + - config() on postinstall_script now accepting .dist and .sample config file extensions + - added git_source section + - createpkg: + - command line support for creating multiple packages + - fakeroot support + - new options --import, --status, --update and --commit to manage subversion repository, among others + - subversion integration + - minor changes + - renamed config parameter CREATE_ARCH to CREATEPKG_ARCH + - renamed all "MAKEPKG" config parameters to "PACKAGES", "MAKEPKG_REPOS" to "PACKAGES_DIR" + - cleaner -s option output + - new config parameters PACKAGES_REPOS_STYLE, MOVE_SLACK_REQUIRED, MKBUILDS_SVN_USER, + PACKAGES_SVN_USER, PACKAGES_SVN_GROUP, MKBUILDS_SVN_GROUP, PACKAGES_REPOS_NOARCH, + PACKAGES_SVN, CREATEPKG_AUTHOR, SIGN_PACKAGES, SIGN_PACKAGES_USER. SIGN_PACKAGES_KEYID, + SIGN_PACKAGES_WITH_GPG_AGENT, SOURCE_DIR_USER, SOURCE_DIR_GROUP, SIGN_MANIFESTS, + SIGN_MANIFESTS_KEYID, SIGN_MANIFESTS_WITH_GPG_AGENT, FORCE_MANIFEST_CHECK, + FORCE_MANIFEST_CHECK_SIGNATURE, MKBUILD_AUTHOR, MKBUILD_AUTHOR_INITIALS + - lspkg: fix on package search routine + - jail-commit: using unified diff + +0.6pre30 +======== + + - common.sh: fixed package_name when dealing with files under /var/log/packages + +0.6pre29 +======== + + - templatepkg: fixed issue on adding files in a template. + - simplaret: "--sync" and "sync" now synonyms to "--update" and "update". + +0.6pre28 +======== + + - generic.mkSlackBuild: new section copy_config_files + - lspkg: change ls /var/log/packages/$1 to ...$1-[0-9] + - mkjail: fixed #27 + - jail-update: installs/remove packages according the template (closes #10) + - simplaret: + - option --install working for multiple packages (closes #1) + - option --remove working for multiple packages + - mkpatch: fixed infinite loop on invalid diff action + - mkbuild 1.2.7: + - new ACTION bugfix + - search result bugfix + - protect MKBUILD_NAME and ACTION variables with "" in line 266 + - createpkg 1.1.13: + - severals EXIT_CODE corrections + - search result bugfix + +0.6pre27 +======== + + - using Makefile instead of simplepkg.SlackBuild + - generic.mkSlackBuild: fix on svn_source + - createpkg 1.1.12: + - change indentation do two spaces; + - add option --debug|-d to debug SlackBuilds scripts; + - add EXIT_CODE to output status from createpkg; + - mkbuild 1.2.6: + - add --search|-s option; + - mkbuild copy all file in current directory different of *.SlackBuild, + *.old, *.tmp, and slack-required to mkbuild directory, in + commit_mkbuild function; + - mkbuild copy all file in current directory different of *.mkbuild, + *.old, and *.tmp to slackbuild repository, in commit_slackbuild + function; + - add EXIT_CODE to output status from mkbuild; + +0.6pre26 +======== + + - createpkg: + - add LANG=en_US in SlackBuild command line + - mkbuild: + - bugfix: add "" to protect all parameters in edit_file function call; + - change line 346-346 with "sed -i" command; + - add SVN_MOD variable to control svn source code; + - add control to SVN_MOD and URL "none" in activate_sections function; + - desable sections download_source, md5sum_download_and_check_0, + md5sum_download_and_check_1, gpg_signature_check untar_source, in + SVN_MOD or URL "none"; + - enable section get_svn_source in SVN_MOD; + - EXTENSION, UNPACKER, UNPACKER_FLAGS, DECOMPRESSOR, and DECOMPRESSOR_TEST_FLAG + desable in SVN_MOD or URL "none"; + - generic.mkSlackBuild: + - change PKG_SRC="$PWD...{ print $8 }'`" to ...{ print $NF }'`" + - add svn_source section to grab subversion sources; + - comment lines limited to 79 columns; + - model.mkbuild: + - add "off:svn_source" line; + +0.6pre25 +======== + + - generic.mkSlackBuild: + - fixed gziped patch support at patch_source section + - added LDFLAGS for x86_64 + +0.6pre24 +======== + + - mkbuild: added LICENSE and SIGNATURE on default [[DOCUMENTATION FILES]] + - perl.mkSlackBuild: + - gpg_signature_check: support for [[SIGNING KEY ID]] parameter + - minor fix + +0.6pre23 +======== + + - generic.mkSlackBuild: + - new section copy_init_scripts + - gpg_signature_check: support for [[SIGNING KEY ID]] parameter + +0.6pre22 +======== + + - generic.mkSlackBuild: + - enhanced patch_source section with [[PATCH URLS]] support + - minor changes + +0.6pre21 +======== + + - generic.mkSlackBuild: + - added -fPIC on SLKCFLAGS for x86_64 + +0.6pre20 +======== + + - generic.mkSlackBuild: + - new section create_build_user_and_group + - new section move_config_files + - more gpg_signature_check section fixes + - new functions at postinstall_script section + - perl.mkSlackBuild: + - more gpg_signature_check section fixes + +0.6pre19 +======== + + - mkbuild-1.2.3: + - help function update + - createpkg-1.1.11: + - help function update + - generic.mkSlackBuild / perl.mkSlackbuild: + - gpg_signature_check section fixes + +0.6pre18 +======== + + - mkbuild-1.2.2: + - function change_others_parameters works of the beginning of the + archive .mkbuild until the line initiated for "#>>" + - added "--sync" option + - change indent spaces to 2 + - "show slackbuild path" option (-sp) and related functions had been removed + - removed others small bugs + - common.sh: fixed default_arch + - simpletrack: error message + +0.6pre17 +======== + + - mkpatch add simple patch suport to mkbuild + - mkpatch-1.1: + - --help, -h option suport + - change select line: 'sed "#i g;d"' is 30% most fast that 'sed -n "#i p"' + - change 'while' loop to most speed in patch application + - bug fixe: replace 'return' for 'exit' command + - mkbuild-1.2.0: + - added suport to mkpatch section in .mkbuild (apply_mkpatch function) + +0.6pre14 +======== + + - simplaret: ignoring slack-required lines starting which "#" + +0.6pre13 +======== + + - mkbuild-1.1.11: + - -sp, --slackbuild-path option added + - ACTION variable added (values are: new, show-path, and build) + - MKBUILD_NAME and MK_INPUT_FILE variables are the same ones + - Several 'sed - i' applied + - Changed caracter of separation in the command 'sed' for ¦ + - Reorganized the function get_slackbuild_path + - Call for the function start_build moved of position + +0.6pre12 +======== + + - common.sh: small change + + - generic.mkSlackBuild / perl.mkSlackBuild: minor fixe + + - mkbuild-1.1.10: + - added inputs --path-files and --nps-strip + - remove old code 'let i++' in set_parameters function + - PATCH FILES parameter default set to "" + - NUMBER OF PREFIX SLASHES TO STRIP parameter default set to "1" + - change_others_parameters function minor fixe + - variable ARCH="noarch" in SlackBuild file, if [[ARCH]]="noarch" + +0.6pre11 +======== + + - common.sh: + - enhanced system arch and version detection + - minor changes + + - simplaret: + - changed distro folder routine + - added --help | help command line option + - added simplified syntax: + + simplaret ekiga # should work as simplaret install ekiga + + - generic.mkSlackBuild / perl.mkSlackBuild: minor fixes + +0.6pre1-10 +========== + + - added perl.mkSlackBuild + + - generic.mkSlackBuild-0.9.0: + - added [[BUILD NUMBER]] parameter + - added variable PKG_WORK(=$TMP/$SRC_NAME) to package work directory + - PKG_SRC now is `ls -la | awk '/^d/ { print $8 }'`, directory in $PKG_WORK + + - model.mkbuild-0.9.0: + - added [[BUILD NUMBER]]="" parameter + + - createpkg-1.1.9: + - added option --all, to build all SlackBuilds in repository + - added number of parameters check + - integrate handle_error with common.sh + - moved handle_error and error_codes to common.sh (see above) + - usage function add exit program + - change ERROR_... codes to ERROR_CREATEPKG_... + - added SLACKBUILDS_SVN variable + - called to svn functions change to send SLACKBUILDS_DIR and SLACKBUILDS_SVN variables + - error 2 (usage function) change to usage function call + + - mkbuild-1.1.9: + - added [[BUILD NUMBER]]="" parameter support + - bugfix: removed [] from is_number function call + - correction of some codes of error and calls the handle_error function + - added commit mkbuild, commit slackbuild , and commit all options + - removed error_codes and mkbuild_error to common.sh + - COMMIT variable change to COMMIT_SLACKBUILD + - added variable COMMIT_MKBUILD + - analysis of the variable NUMJOBS moved close to the reading from parameter NUMBJOBS + - reading of the variable SLACKBUILD_PATH was moved for the end of the list of parameters + - is_number function moved to common.sh + - added validate_parameter input check + - added support to the "empty parameter" in validate_parameter function + - added variables SLACKBUILDS_SVN, MKBUILDS_DIR and MKBUILDS_SVN + - added variables BASENAME (program name) + - COMMIT_SLACKBUILD and COMMIT_MKBUILD default set to off + - UNPACKER bugfix + - DECOMPRESSOR bugfix + - added most flexibility in the creation of initial ".mkbuild" file + - added commit_mkbuild function + - bugfix: input of set_parameters ($@) protected with "" + - bugfixes: -a, -u, and -ai options + + - common.sh + - ERROR_PAR_NUMBER - incorrect number of parameters + - ERROR_COMMON_NOT_FOUND - file common.sh not found + - added error_codes function + - added handle_error function + - added svn functions: + - build_repo (build a svn repository) + - check_repo (check repository) + - sync_repo (synchronize repository) + - added is_number function. + Check if input is a number + + - bugfixes: + - common.sh: added ;; in the end from line 787 + - common.sh: change handle_error exit to "is_number $1 && exit $1 || exit 1" + - createpkg: protect parameters in solve_dep call with "" + - mkbuild: change "PACKGE NAME" parameter to "PKG NAME" + - model.mkbuild: change "PACKGE NAME" parameter to "PKG NAME" + + - simplepkg.conf: + - new config variables: + - MKBUILDS_DIR (mkbuilds directory repository) + - SLACKBUILDS_SVN (SlackBuild svn source) + - MKBUILDS_SVN (Mkbuild svn source) + + - model.mkbuild: + - Some changes to integrate to applicatory the external ones: + - [[SLACKBUILD AUTHOR]] default change to "[[YOUR NAME]]" + - [[SLACKBUILD AUTHOR INITIALLS]] default change to "[[YOUR SIGNATURE]]" + - [[DONLOAD FOLDER URL]] default change to "[[DEFAULT URL]][[PACKGE NAME]]" + - all [[NAME]] change to [[PACKGE NAME]] + - added [[ARCH]]="" parameter + + - lspkg-0.4: + - added error code 1 to fail exit + +0.6pre1-8 +========= + + - common.sh: + - fixed http://slack.sarava.org/trac/ticket/19 + + - added simpletrack script + + - simplaret: + - lots of fixes (thanks Diogo for finding and reporting two of them) + - performance enhancement on --upgrade + + - createpkg: + - small fixes + - starting support for repository management + + - mkbuild: + - lots of changes + + - documentation update + +0.5pre23 +======== + + - updated documentation + +0.5pre22 +======== + + - simplaret: + - small fix + - common.sh: + - fixes on metafiles generation + +0.5pre21 +======== + + - templatepkg: + - now --delete can also remove the file from a jail + +0.5pre20 +======== + + - small changes + - jail-commit: + - template files security + +0.5pre19 +======== + + - simplaret: + - bugfixes + - options --get and --install now can work + with full file name. + +0.5pre15-18 +=========== + + - bugfixes + +0.5pre14 +======== + + - simplaret + - added variable REPOS_PRIORITY + - added variable SIMPLARET_DOWNLOAD_FROM_NEXT_REPO + + - lspkg: + - small bugfix + + - common.sh: + - on search_template, doesnt return a template from + defaults/ if the function is called with --update + + - utils/add-slack-required: + - command line enhancement + +0.5pre9 - 0.5pre13 +================== + + - bugfix releases + +0.5pre8 +======= + + - lspkg: + - bugfix + + - common.sh: + - bugfix in function slash + +0.5pre7 +======= + + - simplaret: + - fixed bug for ROOT definitions when there is packages + inside of folders different than ROOT_PRIORITY + +0.5pre6 +======= + + - repos: + - FILE_LIST generation fix + + - mkjail: + - new config variable ADD_TO_JAIL_LIST controls wheter to + add new jails into the JAIL_LIST file + +0.5pre5 +======= + + - jail-commit + - SILENT env variable to decrease verbosity + +0.5pre4 +======= + + - templatepkg: + - small fixes + - help usage summary improvements + - now using variable TEMPLATE_FOLDER + - SILENT env variable to decrease verbosity + - option -p | --post-install renamed to -b | --batch-edit + - option -p | --post-install now used to build a package from a template + - option -d | --delete now can also remove post-install scripts + + - common.sh + - small fixes + - now using variable TEMPLATE_FOLDER + + - jail-commit: + - calling templatepkg silently + - small fixes + +0.5pre3 +======= + + - again, lots of bugfixes + + - jail-commit: + - update a template just once if finds more than one entry + for a template in the jailist + +0.5pre2 +======= + + - lots of bugfixes + + - templatepkg: + - now creates missing components in a template + +0.5pre1 +======= + + Lots of changes! + + - repos: cosmetic changes + + - lspkg: + - support for $ROOT env variable + - some improvements + + - CHANGELOG cleanup + + - subversion repository support for templates + + - metapkg moved to utils/ + + - simplaret: + - new config variables: + - STORE_ROOT_PATCHES_ON_PATCHES_DIR + - SIGNATURE_CHECKING + - ROOT=/otherroot works for --install, --remove and --upgrade + - signature checking + - dependency checking through slack-required + + - mkjail: + - added support for slack-required as templates + - templates now can be stored either on + - /etc/simplepkg/template_name.template + - /etc/simplepkg/templates/template_name.template + - /etc/simplepkg/templates/template_name/template_name.template + + - jail-update + - old script renamed to jail-commit + - now update a jail from a template + - svn repository support + + - jail-commit + - new script, commit changes from a jail to the templates + - svn repository support + + - templatepkg: + - major rewrite + - svn repository support + - now supports a tagfile or slack-required as a template + - new/changed options + -c | --create: improvements + -a | --add: changed to add files into a template + -u | --update: update a template + -d | --delete: delete files or folders from a template + -s | --sync: sync /etc/simplepkg/templates working copy + -e | --export: export /etc/simplepkg/templates to a svn repository + -i | --import: grab /etc/simplepkg/templates from a svn repository + -r | --remove: remove a template + -l | --list: list templates + -p | --post-install: add or edit post-installation scripts + -t | --template-edit: edit template package list + -h | --help: display this summary + +0.4.9pre18-23 +============= + + - simplaret: + - enhanced http retrieval: curl support + - enhanced verbosity + - get-patches small changes + - various fixes + +0.4.9pre10-17 +============= + + - lots of simplaret fixes + +0.4.9pre9 +========= + + - createpkg: + - speedup + - ncftpget support + - timeout support + - sets the correct architecture + + - deleted jail-upgrade + + - removed swaret support + +0.4.9pre8 +========= + + - createpkg: bugfix + + - common.sh: + - enhanced config file evaluation + - fixed function default_arch + + - simplaret: + - config evaluation via common.sh + - new config parameter SIMPLARET_PURGE_PATCHES + +0.4.9pre7 +========= + + - repos: added patches/ metafile creation + + - jail-upgrade: + - added option CONSIDER_ALL_PACKAGES_AS_PATCHES + - merged swaret and simplaret upgrade procedures + - act recursively on patches' folder + + - simplaret: lots of changes, most important are: + - new repository scheme, take a look at repos.conf.new. + - --get looks first to PATCHES repositories, then ROOT, + then REPOS and finally at NOARCH repositories; the + firts matching package is downloaded. + - new config parameter ROOT_PRIORITY set the priority + of folder lookup at a ROOT repository, defaults to + "patches slackware extra testing pasture". + - for --get, check if an already existing package + in the local repository has the same version and + build number, otherwise erase the old and download + the new one. + - fixed --get-paches + - added --upgrade option + - added --install + - added --remove + - new config parameter DOWNLOAD_EVEN_APPLIED_PATCHES + + - createpkg: lots of changes + +0.4.9pre6 +========= + + - createpkg: + - fixes + - now with slackbuild error handling + - increased verbosity + + - small fixes on rebuildpkg + + - lspkg enhancements + + - simplaret fix on --purge + + - updated default repos.conf + +0.4.9pre5 +========= + + - added script "repos" + + - moved simplaret to /usr/bin + +0.4.9pre4 +========= + + - createpkg: better command line evaluation, + now using "upgradepkg --install-new" to + install a package and added the command + line option --no-deps so createpkg doesn't + goes down to solve all slack-required + dependencies. + +0.4.9pre3 +========= + + - small fix on createpkg when handling with + slackbuilds with similar names + +0.4.9pre2 +========= + + - fixed simplepkg.SlackBuild + + - fixed doinst.sh + + - re-organized the source repository + + - added createpkg + + - updated README and README.pt_BR + +0.4.8 +===== + + - simplaret: removed extra folder from slamd64 definition + + - fixed a typo + +0.4.7 +===== + + - templatepkg bugfix on blank template lines and on package deletion + changed simplaret working dir in simplaret.conf.new + +0.4.6 +===== + + - small bugfix on jail-update that prevented template update + +0.4.5 +===== + + - vserver template update + +0.4.4 +===== + + - WARNING option on config file for simplaret + + - SILENT env var, if a non-zero value, keeps simplaret + work silenty when purging and works like if WANRING is set + to not null. + + - added SIMPLARET_DELETE_DURING config parameter: when set + to a non-zero value deletes each package rigth after its + installation + +0.4.3 +===== + + - added openoffice.org template + +0.4.2 +===== + + - common.sh: fix on install_packages when handling + with similar package names + +0.4.1 +===== + + - templatepkg: fixed tagfiles and comment handling + +0.4 +=== + + - multi-plataform and version management + + now simplepkg supports jails with architectures and versions + others than the main system, read the docs for details. + + - added simplaret: a small script for downloading packages + + - jail-upgrade + + * arch checking via /etc/slackware-version on each jail + * supports multi-arch and multi-version repository + * integrated with simplaret + + - common.sh: improved functions to support simplaret + +0.3.7-0.3.9 +=========== + + - bugfix releases + +0.3.6 +===== + + - added "-u" option to eval_config to ask for a swaret --update + +0.3.5 +===== + + - "main" jail support for jail-update + +0.3.4 +===== + + - Started changelog :) + diff --git a/doc/COPYING b/doc/COPYING new file mode 100644 index 0000000..d60c31a --- /dev/null +++ b/doc/COPYING @@ -0,0 +1,340 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + <one line to give the program's name and a brief idea of what it does.> + Copyright (C) <year> <name of author> + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + <signature of Ty Coon>, 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. diff --git a/doc/TODO b/doc/TODO new file mode 100644 index 0000000..54b686e --- /dev/null +++ b/doc/TODO @@ -0,0 +1,5 @@ +simplepkg todo list +------------------- + +TODO list at http://slack.sarava.org/trac/report + diff --git a/doc/mkbuild-pt_BR.tex b/doc/mkbuild-pt_BR.tex new file mode 100644 index 0000000..2b82598 --- /dev/null +++ b/doc/mkbuild-pt_BR.tex @@ -0,0 +1,854 @@ +\documentclass[12pt,a4paper,oneside]{article} +%\usepackage[T1]{fontenc} +\usepackage[latin1]{inputenc} +\usepackage[dvips]{graphicx} +%\usepackage{subfigure} +\usepackage{mdwlist} +\usepackage{a4} +%\topmargin -.5in +%\addtolength{\hoffset}{-1.0cm} +%\addtolength{\textwidth}{3.0cm} +%\textwidth = 400pt +%\textheight = 680pt + +\makeatletter + +%\usepackage[pdftex]{color,graphicx} +%\DeclareGraphicsExtensions{.jpg,.pdf,.mps,.png} + +\usepackage[brazil]{babel} +\usepackage[dvips]{graphicx} +%\usepackage{textdraw} + +\input texdraw +%\newenvironment{textdraw}{\leavevmode\btexdraw}{\etexdraw} + +\newcommand{\rcap}[1]{Capítulo \ref{#1}} +\newcommand{\rfig}[1]{Figura \ref{#1}} +\newcommand{\rtab}[1]{Tabela \ref{#1}} +\newcommand{\rsec}[1]{Seção \ref{#1}} + +\makeatother + +\begin{document} + + +\title{Construindo SlackBuilds com mkbuild} + +\author{Rudson Alves\\v. 1.2} + +\date{\today} + +\maketitle + +%\pagenumbering{roman} + +\tableofcontents{} +%\listoffigures +%\listoftables + +%\abstract{...} + + +\section*{Introdução} + +O \textit{mkbuild} é um programa em \textit{script shell} que auxiliar na construção de pacotes para o \textit{Slackware}. A grosso modo, o \textit{mkbuild} é um construtor de \textit{Slackbuild}\footnote{\textit{SlackBuilds} são \textit{script} utilizado para a construção de um pacote binário de um programa, no \textit{Slackware}.}. Ele opera a partir de um arquivo de parâmetros e de modelos de \textit{Slackbuilds} parametrizados. + +Este texto apresenta informações úteis para utilização do \textit{mkbuild} na construção destes arquivos de parâmetros, bem como configurar e utilizar modelos de \textit{SlackBuilds} e outras personalizações. + +O \textit{mkbuild} é uma ferramenta distribuída juntamente com o \textit{simplepkg}, um projeto do grupo Slack.Sarava. Para a utilização desta ferramenta você deverá instalar o pacote conforme as instruções abaixo: + +\begin{verbatim} +# LASTVERSION=`lynx -dump http://slack.sarava.org/packages/noarch/ \ + | grep 'simplepkg-.*\.tgz' | awk '{print $2}'` +# wget $LASTVERSION +# installpkg simplepkg-*.tgz +\end{verbatim} + +Para mais informações veja os links abaixo: + +\begin{itemize} + \item http://slack.sarava.org/simplepkg - Descrição de todo o projeto \textit{Simplepkg}, por Rhatto - coordenador do projeto \textit{Slack.Sarava}; + \item http://slack.sarava.org/node/25 - Tutorial básico de instalação do \textit{Simplepkg}, por rafael2k - um grande colaborador. +\end{itemize} + + +\section{O modelo generic.mkSlackBuild} + +O \textit{mkbuild} utiliza o modelo padrão \textit{generic.mkSlackBuild}, armazenado em + +\begin{verbatim} +/etc/simplepkg/defaults/mkbuild/ +\end{verbatim} + +Este modelo é uma versão setorizada do \textit{generic.SlackBuild}, levemente modificada. O \textit{generic.SlackBuild} é um modelo genérico de \textit{Slackbuilds} criado por nosso colega e colaborador Luís, para servir como modelo para a construção dos \textit{Slackbuilds}. Outros modelos setorizados podem ser utilizados pelo \textit{mkbuild}, a única limitação é quanto ao nome da seção \textit{slackdesc}, que não poderá ser alterada. + + +\subsection{Os Campos} + +O modelo \textit{generic.mkSlackBuild} é um \textit{SlackBuild} genérico com vários campos destacados por duplo colchetes, [[ \dots ]], com mostra o trecho abaixo: + +\begin{verbatim} +... +<set_variables> all +# Set variables +CWD="$(pwd)" +SRC_NAME="[[SOURCE NAME]]" +PKG_NAME="[[PACKAGE NAME]]" +ARCH=${ARCH:=[[ARCH]]} +SRC_VERSION=${VERSION:=[[VERSION]]} +PKG_VERSION="$(echo "$SRC_VERSION" | tr '[[:blank:]-]' '_')" +BUILD=${BUILD:=1[[SLACKBUILD AUTHOR INITIALS]]} +... +PREFIX=${PREFIX:=[[PREFIX]]} +PKG_SRC="$TMP/$SRC_NAME-$SRC_VERSION" +</set_variables> +... +\end{verbatim} + +Uma breve descrição destes campos é apresentada na tabela abaixo: \\ +\\ +\begin{tabular}{l|l} +\hline \hline +\textbf{Campo} & \textbf{Descrição}\\ +\hline \hline +PROGRAM NAME & nome do programa \\ +PROGRAM URL & \textit{URL} da fonte do pacote \\ +SLACKBUILD AUTHOR & nome do autor \\ +SOURCE NAME & nome da fonte, sem versão ou extensão \\ +PACKAGE NAME & nome do pacote e ser gerado \\ +ARCH & arquitetura do pacote. Padrão i486 \\ +VERSION & versão do pacote \\ +SLACKBUILD AUTHOR INITIALS & assinatura utilizada pelo autor \\ +PREFIX & prefixo da instalação (/usr, /opt, \dots)\\ +SOURCE EXTENSION & extensão da fonte (bz2, gz, \dots) \\ +UNPACKER & programa de dessempacotamento (geralmenrte "tar") \\ +UNPACKER FLAGS & flags para o desempacotador \\ +DOWNLOAD FOLDER URL & \textit{URL} da pasta onde se encontra a fonte \\ +DECOMPRESSOR & o descompressor para a fonte (gunzip, bunzip2, \dots) \\ +DECOMPRESSOR TEST FLAG & \textit{flag} de teste do descompressor \\ +SIGNING KEY URL & \textit{URL} da chave \textit{gpg} do fonte \\ +SIGNING KEY & chave \textit{gpg} da fonte \\ +MD5SUM EXTENSION & extensão utilizada pelo arquivo \textit{md5sum}\\ +PATCH FILES & arquivo \textit{path} \\ +NUMBER OF PREFIX SLASHES TO STRIP & \dots \\ +SOURCE NAME CONSTRUCTION STRING & string para a construção do nome do arquivo. O padrão é \$SRC\_NAME-\$VERSION.tar.\$EXTENSION \\ +OTHER CONFIGURE ARGS & argumentos de configuração passados ao ./configure \\ +DOCUMENTATION FILES & lista de arquivos para a pasta /usr/doc/PACKAGE \\ +SLACK-DESC & conteúdo do slack-desc, descrição do pacote \\ +REST OF DOINST.SH & conteúdo do doinst.sh \\ +\hline +\end{tabular} +\\\\ + +Em alguns casos o nome do pacote difere do nome da fonte, como é o caso da fonte \textit{sigc++}, que gera o pacote de nome \textit{libsiggc++}. Por este motivo que existem os campos \textit{SOURCE NAME} e \textit{PACKAGE NAME}. Para uma compreensão mais profunda destes campos, aconselho fazer uma análise mais detalhada do modelo \textit{generic.mkSlackBuild}. + + +\subsection{As Seções} + +As seções no modelo \textit{generic.mkSlackBuild}, são iniciadas pela \textit{tag} <nome\_da\_seção> e terminadas com </nome\_da\_seção>, como em um código \textit{html}, \underline{sem espaços}. + +A única seção que não pode ter seu nome alterado é \textit{slackdesc}. Esta seção é editada de uma forma diferenciada pelo \textit{mkbuild} e a alteração de seu nome poderá gerar erro. + +Cada seção possui uma \textit{flag} com os possíveis valores: + +\begin{description} + \item[on] habilitado; + \item[off] desabilitado; + \item[all] sempre habilitado. +\end{description} + +A intenção destas \textit{flags} é gerar um padrão para as seções, deixando em \textbf{all} as seções que deverão estar sempre habilitadas e \textbf{on} ou \textbf{off} seções que podem ser habilitadas ou desabilitadas de acordo com as necessidades do \textit{SlackBuild} que será construído\footnote{Na versão 1.1.x do mkbuild, todas as seções foram configuradas como \textbf{off}, para simplificar a vizualização do script de configuração \textit{.mkbuild}.}. + +As seções padrões do \textit{generic.mkSlackBuild} são listadas na tabela abaixo: +\\\\ +\begin{tabular}{l|l|c|c} +\hline +Seção & Descrição & 1.0.x & 1.1.x\\ +\hline +head & cabeçalho do \textit{SlackBuild} & all & on \\ +slackbuildrc & carrega \textit{script} \textit{slackbuildrc} & off & off \\ +set\_variables & inicia as variáveis & all & on \\ +slkflags & carrega \textit{flags} para compilação & all & on \\ +error\_codes & códigos de erro para o \textit{createpkg} & off & off \\ +start\_structure & cria diretórios para compilação & all & on \\ +download\_source & baixa a fonte do pacote & off & off \\ +md5sum\_download\_and\_check\_0 & verifica \textit{md5sum} da fonte por código & off & off \\ +md5sum\_download\_and\_check\_1 & verifica \textit{md5sum} da fonte por arquivo & off & off \\ +gpg\_signature\_check & verifica assinatura \textit{gpg} da fonte & off & off \\ +untar\_source & desempacota a fonte & all & on \\ +path\_source & aplica \textit{path} a fonte & off & off \\ +configure & configura pacote & off & off \\ +make\_package & compila o pacote & all & on \\ +install\_package & instala o pacote em diretório temporário & all & on \\ +strip\_binaries & limpa binários & off & off \\ +compress\_manpages & comprime páginas de manuais & off & off \\ +compress\_info\_files & comprime arquivos \textit{info} & off & off \\ +install\_documentation & instala documentação & off & off \\ +slackdesc & \textit{slackdesc} do pacote & off & off \\ +postinstall\_script & \textit{script} de pós-instalação & off & off \\ +build\_package & constrói pacote & all & on \\ +clean\_builds & remove fontes e instalação temporária & off & off \\ +\hline +\end{tabular} +\\\\ + +A terceira e a quarta colunas da tebela acima apresentam o status padrão para as seções nas versões 1.0.x e 1.1.x do \textit{mkbuild}. No \textit{mkbuild} versão 1.0.x, as seções \textbf{all} são configuradas no modelo \textit{generic.mkSlackBuild}. A partir da versão 1.1.x estas seções serão definidas como \textbf{on} ou \textbf{off} no \textit{model.mkbuild}, não mais no modelo \textit{generic.mkSlackBuild}. + + +\section{Configuração} + +O \textit{mkbuild} utiliza quatro variáveis de configuração em /etc/simplepkg/simplepkg.conf. São elas: + +\begin{description} + \item[SLACKBUILDS\_DIR] diretório onde serão guardados os \textit{SlackBuilds} e \textit{slack-required} gerados. Necessário para o uso com a opção \textbf{-c}, \textit{commit}. Padrão /var/simplaret/slackbuilds; + \item[MKBUILDS\_DIR] diretório onde serão guardados os \textit{.mkbuilds} criados. Necessário para o uso com a opção \textbf{-c}, \textit{commit}. Padrão /var/simplaret/mkbuilds; + \item[SLACKBUILDS\_SVN] endereço do repositório subversion dos \textit{SlackBuilds}. Mantenha o valor padrão; + \item[MKBUILDS\_SVN] endereço do repositório subversion dos \textit{SlackBuilds}. Mantenha o valor padrão; + \item[COLOR\_MODE] define modo de cores para o \textit{mkbuild} e \textit{createpkg}. Padrão \textit{none}, preto e branco. + \end{description} + + +\section{Criando o SlackBuild do aplicativo pyrex} + +Para fazer um \textit{SlackBuild} com o \textit{mkbuild} é necessário criar um arquivo com os parâmetros que deseja que sejam passados para o modelo. Um arquivo de configuração simples, \textit{sample-Pyrex-small.mkbuild}, é apresentado abaixo: + +\begin{verbatim} +#-------------------- +# Variables +#-------------------- +# Author name +[[SLACKBUILD AUTHOR]]="Adalberto Simão Nader" + +# +# Complete URL address or URL base address ( without $SRC_NAME-$VERSION... ) +[[DOWNLOAD FOLDER URL]]="http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/Pyrex-0.9.5.1a.tar.gz" + +# +# Default enable sections: +# head, set_variables, slkflags, start_structure, untar_source, +# make_package, install_package, build_package +# Warning: don't remove '#>>' and "#<<" tags. +#>> Start SlackBuild Sections: + on: head + on: slackbuildrc + on: set_variables + on: slkflags + on: error_codes + on: start_structure + on: download_source + on: md5sum_download_and_check_0 + on: untar_source + on: configure + on: make_package + on: install_package + on: strip_binaries + on: install_documentation + on: slackdesc + on: build_package + on: clean_builds +#<< End SlackBuild Sections + +#------------------ +# Sections changes +#------------------ +#>slackdesc +pyrex: Pyrex by Slack.Sarava +pyrex: +pyrex: Pyrex is a language specially designed for writing Python extension +pyrex: modules. Its designed to bridge the gap between the nice, high-level, +pyrex: easy-to-use world of Python and the messy, low-level world of C. +pyrex: +pyrex: +pyrex: +pyrex: +pyrex: +pyrex: +#<slackdesc +\end{verbatim} + +Isto é o suficiente para fazer o \textit{SlackBuild} do \textit{Pyrex}. Para construir o \textit{SlackBuild} basta chamar o \textit{mkbuild} passando este arquivo de parâmetros: + +\begin{verbatim} +$ mkbuild sample-Pyrex-small.mkbuild +$ ls +pyrex.SlackBuild pyrex.mkbuild sample-Pyrex-small.mkbuild +pyrex.SlackBuild.old sample-Pyrex-large.mkbuild +\end{verbatim} + +Ele irá criar os arquivos \textit{pyrex.SlackBuild} e \textit{slack-required}, se o parâmetro \textit{SLACK REQUIRED} for passado. Arquivos antigos serão renomeados para \textit{.old}. + +Um modelo mais completo, com todos os parâmetros, \textit{sample-Pyrex-large.mkbuild}, é disponibilizado junto com o \textit{mkbuild}. Nas seções seguintes é apresentado uma breve descrição dos parâmetros e seções deste arquivo de parâmetros. + + +\subsection{Descrição dos parâmetros do arquivo \textit{.mkbuild}} + +Embora existam muitos parâmetros no modelo \textit{generic.mkSlackBuild}, nem todos são necessários para a construção do \textit{SlackBuild}. Neste exemplo foram passados apenas dois parâmetros: + +\begin{description} + \item[SLACKBUILD AUTHOR] nome do autor; + \item[DOWNLOAD FOLDER URL] url completa da fonte do pacote. + \end{description} + +O mkbuild remove o nome do pacote, versão, assinatura do autor e várias outras informações destes dados, seguindo alguns critérios descritos a seguir. + +A sintaxe para a passagem de parâmetros ao \textit{mkbuild} pelo arquivo de parâmetros \textit{.mkbuild} é + +\begin{verbatim} +[[DESCRIÇÃO DO PARÂMETRO]]="Parâmetro entre aspas duplas" +\end{verbatim} + +As aspas duplas podem ser omitidas\footnote{Nas versões inferiores a 0.9.9, do \textit{mkbuild}, a aspas dupla é o delimitador e por isto é obrigatório. Um parâmetro passado sem o aspas duplo será interpretado como um parâmetro vazio, nestas versões.}. O delimitador utilizado pelo \textit{mkbuild} é o primeiro caracter igual (=) a aparecer na linha e o fim de linha. Qualquer outra ocorrência de caracter igual será lido como parte do parâmetro. O mesmo acontece com comentários colocados após o caracter igual. Por exemplo, na linha abaixo: + +\begin{verbatim} +[[PARÂMETRO TEST]]=Este parâmetro é um teste # Este comentário será lido. +\end{verbatim} + +\noindent a leitura do parâmetro \textit{PARÂMETRO TEST} retornará: + +\begin{verbatim} +Este parâmetro é um teste # Este comentário será lido. +\end{verbatim} + +Segue abaixo uma breve descrição dos parâmetros utilizados pelo modelo \textit{generic.mkSlackBuild}. + +\subsubsection{SLACKBUILD AUTHOR e SLACKBUILD AUTHOR INITIALS} + +O parâmetro \textit{SLACKBUILD AUTHOR} deve conter o nome ou apelido do responsável pelo \textit{SlackBuild}. A declaração deste parâmetro é obrigatória e sem ele o \textit{mkbuild} irá interromper a construção do \textit{SlackBuild}. + +\begin{verbatim} +[[SLACKBUILD AUTHOR]]="Adalberto Simão Nader" +\end{verbatim} + +O parâmetro \textit{SLACKBUILD AUTHOR INITIALS} é construído a partir da primeira letra de cada nome passado pelo parâmetro \textit{SLACKBUILD AUTHOR}, em letras minúsculas. Neste caso a assinatura será "\verb!asn!", as iniciais de \textit{Adalberto Simão Nader}. + +Caso deseje passa outro valor basta adicionar a linha abaixo, ao arquivo de parâmetros. + +\begin{verbatim} +[[SLACKBUILD AUTHOR INITIALS]]="adal" +\end{verbatim} + + +\subsubsection{DOWNLOAD FOLDER URL} + +O parâmetro \textit{DOWNLOAD FOLDER URL} é outro parâmetro obrigatório em um arquivo \textit{.mkbuild}. Este parâmetro pode conter o endereço completo da fonte do pacote: + +\begin{verbatim} +[[DOWNLOAD FOLDER URL]]="http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/Pyrex-0.9.5.1a.tar.gz" +\end{verbatim} + +Neste caso várias informações são removidas deste parâmetro. Este parâmetro pode ainda conter apenas o endereço do diretório de onde a fonte poderá ser encontrada: + +\begin{verbatim} +[[DOWNLOAD FOLDER URL]]="http://www.cosc.canterbury.ac.nz/greg.ewing/python/Pyrex/" +\end{verbatim} + +Neste caso, é necessário a definição de outros parâmetros necessários para a construção do nome do pacote, como \textit{SOURCE NAME, PACKAGE NAME, VERSION e EXTENSION}, descritos a seguir. + + +\subsubsection{SOURCE NAME, PACKAGE NAME, VERSION e EXTENSION} + +O \textit{SOURCE NAME} é removido do \textit{URL}, caso não seja passado como parâmetro. + +Para que o \textit{SOURCE NAME} seja carregado corretamente, é necessário que o nome da fonte tenha a forma padrão: + +\begin{verbatim} +NOME-DO-PROGRAMA-VER.SÃO.tar.EXTENSÃO +\end{verbatim} + +O nome do programa pode ter vários campos separados por um hífen "\verb!-!", já a versão, pode possuir vários números, ou mesmo letras, separados por ponto e terminados por um "\verb!.tar.!". A extensão deve vir logo após o "\verb!.tar.!". + +A variável \textit{PACKAGE NAME}, é construída com o mesmo valor de \textit{SOURCE NAME}, mas em letras minúsculas. + +Desta forma, a divisão dos campos no exemplo do aplicativo Pyrex, acima, terá o mesmo valor que as declarações dos parâmetros abaixo: + +\begin{verbatim} +[[SOURCE NAME]]="Pyrex" + +[[PACKAGE NAME]]="pyrex" + +[[VERSION]]="0.9.5.1a" + +[[EXTENSION]]="gz" +\end{verbatim} + +Observe que a precedência é a passagem do valor como parâmetro, e não a sua construção. + + +\subsubsection{UNPACKER e UNPACKER FLAGS} + +\textit{UNPACKER} contêm o nome do programa desempacotador das fontes, geralmente o comando "\verb!tar!", enquanto que o parâmetro \textit{UNPACKER FLAGS}, carrega as flags para o desempacotador. Os seus valores padrões são: + +\begin{verbatim} +[[UNPACKER]]="tar" +[[UNPACKER FLAGS]]="--no-same-owner --no-same-permissions -xvf" +\end{verbatim} + + +\subsubsection{SOURCE NAME CONSTRUCTION STRING} + +Deve conter uma string para a construção do nome da fonte. O valor padrão é + +\begin{verbatim} +[[SOURCE NAME CONSTRUCTION STRING]]="$SRC_NAME-$VERSION.tar.$EXTENSION" +\end{verbatim} + +Observe que os parâmetros passados não são processados, como ocorre em uma leitura de uma variável num bash \textit{script}. Eles são lidos como se fossem uma cadeia de caracteres, por isto não tente escapar o \$ na construção do nome, ou o nome da fonte não será construído corretamente na execução do \textit{SlackBuild}. + +Embora a variável \$EXTENSION apareça na construção do nome da fonte, seu valor será substituído durante a construção do \textit{SlackBuild} pelo \textit{mkbuild}. Por isto que não existe inicialização desta variável no modelo \textit{generic.mkSlackBuild}. + + +\subsubsection{DECOMPRESSOR e DECOMPRESSOR TEST FLAG} + +Os parâmetros \textit{DECOMPRESSOR} e \textit{DECOMPRESSOR TEST FLAG} são determinados por análise do parâmetro \textit{EXTENSION}, com os valores apresentados na tabela abaixo: +\\\\ +\begin{tabular}{l|l|c} +\hline +EXTENSION & DECOMPRESSOR & DECOMPRESSOR TEST FLAG \\ +\hline +gz, GZ & gunzip & -t \\ +bz2, BZ2 & bunzip2 & -t \\ +zip, ZIP & unzip & -t \\ +\hline +\end{tabular} + +Caso possua uma fonte comprimida por um compressor diferente, passe estes parâmetros pelo arquivo de parâmetros, \textit{.mkbuild}. + +\begin{verbatim} +[[DECOMPRESSOR]]="programa descompressor" +[[DECOMPRESSOR TEST FLAG]]="flag de teste" +\end{verbatim} + + +\subsubsection{DOCUMENTATION FILES} + +O valor padrão para \textit{DOCUMENTATION FILES} é + +\begin{verbatim} +[[DOCUMENTATION FILES]]="NEWS TODO README AUTHORS INSTALL ChangeLog MAINTAINERS COPYING readme.*" +\end{verbatim} + +Estes são os nomes mais comuns dos arquivos de documentação, que geralmente são disponibilizados na raiz do diretório das fontes dos programas. O ideal é descompactar a fonte e verificar os arquivos de documentação disponíveis, para passá-los como parâmetro. + + +\subsubsection{PREFIX} + +A maioria das fontes de programas disponibilizados atualmente, utilizam uma opção "\verb!--prefix!" no seu \textit{configure}, para determinar o diretório onde o programa será instalado. Nas versões inferiores a 12.0 do \textit{Slackware} o valor desta variável variava entre /usr, /opt e /usr/X11. Na versão 12.0, e provavelmente nas superiores, os diretórios /opt e /usr/X11 foram removidos e todos os pacotes estão sendo instalados em /usr. Por isto o seu valor padrão é /usr. + +\begin{verbatim} +[[PREFIX]]="/usr" +\end{verbatim} + + +\subsubsection{NUMBER OF JOBS} + +O parâmetro \textit{NUMBER OF JOBS} é usado para indicar ao comando \textit{make} o número de processos que podem ser iniciados simultaneamente durante a compilação da fonte. A grande maioria dos programas atuais podem ser compilados em dois ou mais processos simultâneos. Isto reduz sensivelmente o tempo de compilação de um pacote, mesmo que sua máquina possua apenas um processador. Muitos \textit{SlackBuilds} oficiais do \textit{Slackware} utilizam este parâmetro configurado para "\verb!7!" processos, ou seja "\verb!-j7!". Este parâmetro pode ser passado como um número ou com a flag "\verb!-j!", como nos exemplos abaixo. + +\begin{verbatim} +[[NUMBER OF JOBS]]="7" +\end{verbatim} + +\noindent ou + +\begin{verbatim} +[[NUMBER OF JOBS]]="-j7" +\end{verbatim} + + +\subsubsection{SLACK REQUIRED} + +Este parâmetro é composto pela lista de pacotes necessários para a construção do aplicativo. Estes pacotes serão arranjados no arquivo \textit{slack-required}. O formato para este parâmetro é apresentado na linha abaixo: + +\begin{verbatim} +DEPENDÊNCIA_1 [CONDIÇÃO_1] [VERSÃO_1]: DEPENDÊNCIA_2 [CONDIÇÃO_2] [VERSÃO_2]: DEPENDÊNCIA_3 [CONDIÇÃO_3] [VERSÃO_3]: ... +\end{verbatim} + +As condições possíveis são apresentadas na tabela abaixo: +\\\\ +\begin{tabular}{c|l} +\hline +CONDIÇÃO & significado \\ +\hline += & igual \\ +> & maior \\ +>= & maior ou igual \\ +\hline +\end{tabular} + +Os campos \textit{CONDIÇÃO} e \textit{VERSÃO} podem ser omitidos. Cada pacote da dependência deve ser separado por um ":". + +Para o \textit{SLACK REQUIRED} definido com a linha: + +\begin{verbatim} +[[SLACK REQUIRED]]="dep1 >= 1.1.1: dep2 >= 2.2.2:dep3:dep4:dep5 = 1.0" +\end{verbatim} + +\noindent será gerado o arquivo \textit{slack-required} abaixo: + +\begin{verbatim} +# Dependency list to Pyrex +# +# dependency [condition] [version]] +dep1 >= 1.1.1 +dep2 >= 2.2.2 +dep3 +dep4 +dep5 = 1.0 +\end{verbatim} + + +\subsubsection{SLACKBUILD MODEL} + +Este parâmetro contém o nome do modelo utilizado para gerar os \textit{SlackBuilds}. O valor padrão é \textit{generic.mkSlackBuild}. Outros modelos podem ser utilizados adicionando-se o arquivo do modelo no diretório /etc/simplepkg/defaults/mkbuild/. A linha abaixo + +\begin{verbatim} +[[SLACKBUILD MODEL]]="generic.mkSlackBuild.2" +\end{verbatim} + +\noindent define o modelo \textit{generic.mkSlackBuild.2} para a construção do \textit{SlackBuild}. + + +\subsubsection{SLACKBUILD PATH} + +Este parâmetro é necessário apenas para uso com a opção "\verb!-c!", \textit{commit}. Ele indica o diretório, na estrutura de diretórios do Slack.Sarava, onde o \textit{SlackBuild} construído deverá ser armasenado. Se este parâmetro não for passado, o \textit{mkbuild} irá pesquisá-lo no repositório do \textit{gentoo}, pela \textit{internet}\footnote{Esta pesquisa automática do mkbuild tem se mostrado pouco eficiente. Por isto é aconselhável verifica com um navegador a localização do \textit{SlackBuild} em http://gentoo-portage.com.}. Caso não consiga resolver com esta pesquisa, o \textit{SlackBuild} será colocado em um diretório padrão para \textit{scripts} não classificados, "\verb!others/unclassified/$PKG_NAME!". + +\begin{verbatim} +[[SLACKBUILD PATH]]="dev/python/pyrex" +\end{verbatim} + +A estrutura de diretórios para armazenamento dos \textit{SlackBuilds} adotadas pelo \textit{Slack.Sarava} segue o mesmo padrão do \textit{portage} do \textit{gentoo}. + + +\subsubsection{Outros Parâmetros} + +Outros parâmetros podem ser passados para substituição no modelo \textit{generic.mkSlackBuild}, como o parâmetro \textit{MD5SUM EXTENSION} no trecho abaixo: + +\begin{verbatim} +#[[PATCH FILES]]="" +#[[MD5SUM CODE]]="" +[[MD5SUM EXTENSION]]="047574eb5d1b7848a70d4130035f1f3c" +#[[SIGNING KEY]]="" +#[[SIGNING KEY URL]]="" +#[[PATCH FILES]]="" +\end{verbatim} + +Além destes parâmetros padrões do \textit{generic.mkSlackBuild}, qualquer outro parâmetro pode ser criado e incluído ao modelo. Para isto é necessário que seu nome seja incluído entre duplo colchetes como no exemplo abaixo: + +\begin{verbatim} +[[NEW PARAMETER]]="new value" +\end{verbatim} + +O \textit{mkbuild} irá procurar a ocorrência da seqüência \textit{[[NEW PARAMETER]]} no modelo passado por \textit{[[SLACKBUILD MODEL]]} e irá substitui-lo por "\verb!new value!". + + +\subsection{Habilitando seções} + +As seções do modelo \textit{generic.mkSlackBuild} são habilitadas na seção iniciada por "\verb!#>>!" e terminada por "\verb!#<<!", no arquivos de parâmetros. Como as seções estão desabilitadas no modelo padrão, \textit{generic.mkSlackBuild}, esta seção do arquivo de parâmetros tem apenas que habilitar as seções desejadas do modelo. + +\begin{verbatim} +#>> Start SlackBuild Sections: + on: head + on: slackbuildrc + on: set_variables + on: slkflags + on: error_codes + on: start_structure + on: download_source +off: md5sum_download_and_check_0 +off: md5sum_download_and_check_1 +off: gpg_signature_check + on: untar_source +off: patch_source + on: configure + on: make_package + on: install_package + on: strip_binaries +off: compress_manpages +off: compress_info_files + on: install_documentation + on: slackdesc +# esta linha é ignorada +off: postinstall_script + on: build_package + on: clean_builds +#<< End SlackBuild Sections +\end{verbatim} + +No caso do exemplo acima, são desabilitadas as seções: \textit{md5sum\_download\_and\_check\_0}, \textit{md5sum\_download\_and\_check\_1}, \textit{gpg\_signature\_check}, \textit{patch\_source}, \textit{compress\_manpages}, \textit{compress\_info\_files} e \textit{postinstall\_script}. Linhas iniciadas por uma tralha, \#, são ignoradas. Como no modelo generic.mkSlackBuild todas as seções estão desabilitadas ("off"), apenas as seções ligadas necessitam ser habilitadas. + + +\subsection{Substituição de seções no modelo} + +Em algumas situações pode ser necessário substituir o conteúdo de uma seção. Estas mudanças são feitas iniciando uma seção, no arquivo de parâmetros, pela \textit{tag} "\verb!#>nome_da_seção!" e terminar pela \textit{tag} "\verb!#<nome_da_seção!". Quando o \textit{mkbuild} localiza estas seções no arquivo de parâmetros, ele substitui as seções padrões, de mesmo nome, pelo conteúdo definido no arquivo de parâmetros. Por exemplo: + +\begin{verbatim} +#>untar_source +# Untar program + +# Change to temp dir +cd "$TMP" + +# Uncompress e untar source +gunzip "$SRC_DIR/$SRC" | tar --no-same-owner --no-same-permissions -xvf || exit $ERROR_TAR + +# Change to source dir +cd "$PKG_SRC" +#<untar_source +\end{verbatim} + +\noindent irá substituir a seção \textit{untar\_source} do modelo \textit{generic.mkSlackBuild}, pelo conteúdo definido no arquivo de parâmetros acima. A única exceção a esta regra é a seção \textit{slackdesc}. + +\begin{verbatim} +#>slackdesc +pyrex: Pyrex by Slack.Sarava +pyrex: +pyrex: Pyrex is a language specially designed for writing Python extension +pyrex: modules. Its designed to bridge the gap between the nice, high-level, +pyrex: easy-to-use world of Python and the messy, low-level world of C. +pyrex: +pyrex: +pyrex: +pyrex: +pyrex: +pyrex: +#<slackdesc +\end{verbatim} + +Para esta seção, o \textit{mkbuild} irá substituir o parâmetro \textit{[[SLACK-DESC]]} pelo conteúdo definido entre "\verb!#>slackdesc!" e "\verb!#<slackdesc!", além de redimensionar a régua de orientação do \textit{slack-desc}. + + +\section{Exemplo 2: mkbuild do dosbox} + +Embora a documentação do comando \textit{mkbuild} seja relativamente longa, não é necessário muito esforço para se fazer um \textit{SlackBuild} de um \textit{pacote bem comportado}. + +Entenda-se por \textit{pacote bem comportado}, pacotes que podem ser construídos pelos comandos: + +\begin{verbatim} + # ./configure && make && make install +\end{verbatim} + +e cujo o nome da fonte obedeça o padrão: \textit{NOME.DO.PACOTE-VERSÃO.tar.EXTENSÃO}. Um bom exemplo disto é o pacote do dosbox, o qual será usado como exemplo nesta seção. + +Inicie a construção do \textit{.mkbuild} com o comando abaixo: + +\begin{verbatim} +# mkbuild -a "<<seu nome>>" -ai "<<iniciais>>" -n dosbox +\end{verbatim} + +Não é necessário o nome e assinatura passados pelas opções \textbf{-a} e \textbf{-ai}, mas é aconselhável. A opção \textbf{-n} diz ao \textit{mkbuild} para copiar o modelo em \textit{/etc/simplepkg/\dots/model.mkbuild}, para o diretório atual com o nome \textit{dosbox.mkbuild}, e aplicar o nome "dosbox" a este modelo. + +Em seguida, edite o arquivo \textit{dosbox.mkbuild}, com um editor de sua escolha, e preencha os campos com os valores abaixo: + +\begin{verbatim} +[[DOWNLOAD FOLDER URL]]="http://downloads.sourceforge.net/dosbox/dosbox-0.71.tar.gz" +[[SLACKBUILD PATH]]="games/emulation/dosbox" + +#>slackdesc +dosbox: DOSBox.slackBuild by Slack.Sarava +dosbox: +dosbox: DOSBox is a DOS-emulator that uses the SDL-library which makes DOSBox +dosbox: very easy to port to different platforms. DOSBox has already been +dosbox: ported to many different platforms, such as Windows, BeOS, Linux, +dosbox: MacOS X... +dosbox: +dosbox: DOSBox also emulates CPU:286/386 realmode/protected mode, Directory +dosbox: FileSystem/XMS/EMS, Tandy/Hercules/CGA/EGA/VGA/VESA graphics, a +dosbox: SoundBlaster/Gravis Ultra Sound card for excellent sound +dosbox: compatibility with older games... +#<slackdesc + +\end{verbatim} + +Por se tratar de um \textit{pacote bem comportado}, o \textit{dosbox.mkbuild} é bem simples. Todas as informações são removidas da URL do programa, não necessitando de mais declarações. O campo \textit{SLACKBUILD PATH} é necessário apenas se você for enviar o \textit{SlackBuild} para o repositório do grupo \textit{Slack.Sarava}. A seção \textit{slackdesc} também não é necessária, mas é importante, pois informa o conteúdo do pacote durante a instalação. + + +\section{Criando um \textit{patch} para pequenas alterações} + +A partir da versão 1.2 do \textit{mkbuild} é possível fazer pequenas alterações ao modelo \textit{generic.mkSlackBuild}, com a aplicação de um \textit{patch} simplificado. Este \textit{patch} é aplicado ao modelo \textit{generic.mkSlackBuild} antes que qualquer outra edição seja feita ao modelo. + +Um \textit{patch} simplificado deve ser definido no arquivo de parâmetros \textit{.mkbuild} entre as \textit{tags} \verb!#p>! e \verb!#p<!, com no exemplo abaixo: + +\begin{verbatim} +... +#p> +... Alterações ... +#p< +... +\end{verbatim} + +As linhas com as alterações devem sempre iniciar com um \textit{caracter de controle}, seguido pelo conteúdo da linha a ser alterada, removida ou conferida ao modelo \textit{generic.mkSlackBuild}. O formato do \textit{patch} usado pelo \textit{mkbuild} segue o mesmo padrão gerado pelo comando \verb!diff -u!, com as seguintes diferenças: + +\begin{enumerate} + \item Não possui numeração de linhas. A posição das alterações é referenciada por uma ou mais linhas de referência. Uma linha de referência deve ser única, ou em caso de várias linhas, a seqüência deve ser única; + \item O número de linhas de referência é variável e não necessita de linhas de referência ao final da alteração; + \item O caracter para separar as alterações é o caracter igual, =. +\end{enumerate} + + +\subsection{Caracteres de controle} + +Os \textit{caracteres de controle} são apenas quatro. Com eles é possível fazer todas as alterações por substituição de linha necessárias em um \textit{patch}. Segue abaixo a descrição destes caracteres de controle: + +\begin{description} + \item[" " (espaço)] este caracter de controle serve para definir linhas de referência, necessárias para localizar a posição das alterações no modelo \textit{generic.mkSlackBuild}; + \item[- (menos)] serve para referenciar linhas que serão removidas do modelo. Este caracter de controle serve ainda para definir linhas de referência, entretanto lembre-se que elas serão removidas; + \item[+ (mais)] serve para indicar linhas que serão adicionadas ao modelo, logo após a referência; + \item[= (igual)] serve para indicar o final de uma alteração e iniciar a próxima. Qualquer coisa colocado após um \textit{caracter de controle} igual, será ignorado. + \end{description} + +Para simplificar a compreensão do funcionamento deste \textit{patch} simplificado, segue abaixo um exemplo para alterações hipotéticas. + + +\subsection{mkpatch: Alterando uma linha} + +Neste exemplo, será alterado o conteúdo da variável \textit{ARCH} para fixá-la em \textit{i586}. Isto pode ocorre na construção de pacotes de programas pré-compilados ou um pacote binário. Para fazer esta alteração, basta acrescentar o \textit{patch} abaixo ao final do arquivo \textit{.mkbuild}: + +\begin{verbatim} +... +#p> + PKG_NAME="[[PACKAGE NAME]]" +-ARCH=${ARCH:=[[ARCH]]} ++ARCH=i586 +#p< +\end{verbatim} + +A primeira linha, \verb!PKG_NAME="[[PACKAGE NAME]]"!, iniciada pelo \textit{caracter de controle} \textbf{espaço}, é uma linha de referência a ser procurada no modelo \textit{generic.mkSlackBuild}, posicionando a alteração ao modelo. A segunda linha, com o \textit{caracter de controle} \textbf{menos}, indica a linha que será removida: \verb!ARCH=${ARCH:=[[ARCH]]}"!. A terceira linha, com o \textit{caracter de controle} \textbf{mais}, será adicionada logo em seguida: \verb!ARCH=i586!. + +Observe que o mesmo poderia ser feito com o \textit{patch} abaixo: + +\begin{verbatim} +... +#p> +-ARCH=${ARCH:=[[ARCH]]} ++ARCH=i586 +#p< +\end{verbatim} + +Como o \textit{caracter de controle} \textbf{menos} também serve como referência e a alteração será feita da mesma forma. + + +\subsection{mkpatch: Aplicando uma segunda alteração} + +Para uma segunda alteração ao modelo, vou alterar a forma de instalação e fazer mais algumas edições a seção \textit{strip\_binaries}: + +\begin{verbatim} +#p> +-ARCH=${ARCH:=[[ARCH]]} ++ARCH=i586 +=== + <install_package> off +-# Install ++# Install Setup +-make install DESTDIR="$PKG" || exit $ERROR_INSTALL +-./setup --prefix="$PKG" || exit $ERROR_INSTALL +=== + # Strip binaries + ( cd "$PKG" +- find . | xargs file | grep "executable" | grep ELF | cut -f 1 -d : | \ +- xargs strip --strip-unneeded 2> /dev/null +- find . | xargs file | grep "shared object" | grep ELF | cut -f 1 -d : | \ +- xargs strip --strip-unneeded 2> /dev/null ++ find . | xargs file | grep ELF | xargs strip --strip-unneeded 2> /dev/null +#p< +\end{verbatim} + +A segunda alteração, troca a linha de comentário adicionado a palavra \verb!Setup! e por fim o comando de instalação, para a chamada \verb!./setup! \dots + +A terceira alteração é feita à seção \textit{strip\_binaries}, onde os dois comando \verb!find! são trocados por um terceiro mais simples. + + +\section{Apêndice-A} + +Vários outros parâmetros podem ser passados ao \textit{mkbuild} pela linha de comando. Um manual completo destas opções pode ser consultado passando \textit{flag} \verb!--help! ou \verb!-h!, ao \textit{mkbuild}: + +\begin{verbatim} +NAME + mkbuild - create SlackBuild script from .mkbuild input file + +SYNOPSIS + mkbuild [OPIONS] [mkbuild_file] + +DESCRIPTION + <mkbuild_file> input file with build rules and variables + + Input options: + -a, --author <author_name> + author name + -ai, --author_initials <initials> + author signature + -bn, --build-number + change build number + -cs, --const_string <string> + construction string to source name + -u, --url <url_address> + url address to source + -pn, --pkg_name <package_name> + package name + -sn, --src_name <source_name> + source name + -pv, --pkg_version <version> + package version + -md, --model <SlackBuild_model> + SlackBuild model file + -j, --jobs <jobs_number> + Number of jobs to run simultaneously + --prefix <install_dir> + Prefix install directory + -pf, --patch-files + List of patch files + -npss, --nps-strip + Number of prefix slashes to strip + + Program options: + -h, --help + this help mesage + -cs, --commit-slackbuild + commit SlackBuilds in local svn SlackBuild tree + -cm, --commit-mkbuild + commit .mkbuild in local svn mkbuild tree + -c, --commit-all + commit SlackBuild and .mkbuild files in local svn tree + -n, --new <mkbuild_name> + start a new mkbuild configure file + -v, --version + program version + -V, --verbose + print debug information + -sp, --slackbuild-path + print SlackBuild path in Slack.Sarava tree + +EXAMPLES + mkbuild -c pyrex.mkbuild + build pyrex.SlackBuild and commit .mkbuild and .SlackBuild in + Slack.Sarava local tree. + mkbuild -a "Jose Araujo" -ai "ja" -n pyrex + make a basic pyrex.mkbuild with author name "Jose Araujo" and + author signature "ja". + mkbuild --prefix /usr/local pyrex.mkbuild + build pyrex.SlackBuild with prefix /usr/local and pyrex.mkbuild + variables and options definitions. + +AUTHOR + Written by Rduson R. Alves + +AVAILABILITY + by svn: svn checkout svn://slack.sarava.org/simplepkg + this mkbuild is found in branches/0.6/ + +REPORTING BUGS + Report bugs to <alves_list@yahoo.com.br> + +COPYRIGHT + Copyright © 2006 Free Software Foundation, Inc. + This is free software. You may redistribute copies of it under the + terms of the GNU General Public License + <http://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the + extent permitted by law. +\end{verbatim} + +Uma opção interessante é a \verb!-c!, utilizada para adicionar e atualizar uma cópia do \textit{SlackBuild} gerado na lista de \textit{SlackBuilds} local. + +Slack.Sarava agradece a toda e qualquer contribuição que possa nos ajudar a manter e a desenvolver este projeto. + +\end{document} + diff --git a/doc/simplaret-en.tex b/doc/simplaret-en.tex new file mode 100644 index 0000000..703aae2 --- /dev/null +++ b/doc/simplaret-en.tex @@ -0,0 +1,312 @@ +\documentclass{article} +\usepackage[brazilian]{babel} +\usepackage[latin1]{inputenc} +\usepackage[dvips]{graphics} +\usepackage{hyperref} +\usepackage{html,makeid} + +\title{Simplaret: simplepkg retrieval tool} +\author{Silvio Rhatto} + +\begin{document}\label{start} +\maketitle + +\begin{abstract} +Simplaret is a \htmladdnormallink{simplepkg}{http://slack.sarava.org/simplepkg-en} tool used to download packages from local and remote repositories. With simplaret, one can grab packages for all archictectures and versions of slackware-like distributions that follows the mirror guidelines, allowing an easy management all jails and slackware installations in a machine, no matter wich arquiteture or version each one has. + +It was inspired in swaret behavior but don't tries to get its complexity level, but execute package download in a different way, where the local repository is organized by archictecture and version. It can also search for packages. It runs on top of pkgtool and is totally non-instrusive and can search, add, remove and upgrade packages. Portuguese version \htmladdnormallink{here}{/simplaret}. +\end{abstract} + +\section{Downloading and installing} + +Simplaret comes with simplepkg, wich installation and configuration is detailed at http://slack.sarava.org/simplepkg. Simplaret uses /etc/simplepkg/simplepkg.conf for its definitions and /etc/simplepkg/repos.conf for repository information. + +The default configuration is placed, respectively, at /etc/simplepkg/defaults/simplepkg.conf and /etc/simplepkg/defaults/repos.conf and should work for most people, but if you want to change something please don't edit the default configuration files as the default setting may change in future releases. If you have a /etc/simplepkg/repos.conf file, then simplaret will just ignore the default repos.conf. + +\section{Using simplaret} + +Simplaret stores its data in system wide folders. Then, some funcionality will just be available if its run with root user capabilities. The first thing you need to do with simplaret is to fetch repository metadata, using + +\begin{verbatim} +simplaret --update +\end{verbatim} + +or simply + +\begin{verbatim} +simplaret update +\end{verbatim} + +as simplepkg supports both command line behaviour (--update or just update). After that, you can search for packages using commands like + +\begin{verbatim} +simplaret search ekiga +\end{verbatim} + +The result should be something like + +\begin{verbatim} +REPOS repository sarava, arch: i386, version: 11.0: ekiga-2.0.5-i586-1rd.tgz +\end{verbatim} + +As we'll see afterwards, "REPOS" means the repository type, "sarava" is the repository name, "arch" is the package architecture (i386 in this case) and "version" is the repository version (11.0 in this case). + +To install this package, just type + +\begin{verbatim} +simplaret install ekiga +\end{verbatim} + +By default, if simplaret finds in the repository a slack-required file for this package (i.e, the file ekiga.slack-required in the same folder of the binary package) then it will try to install all unmet dependencies. This default behaviour can be disabled through config file parameters. + +If you just want to download the package, type + +\begin{verbatim} +simplaret get ekiga +\end{verbatim} + +In the case of simplaret finds more than one package with the same name, it will get in the order that the "search" option shows them. The search precedence can also be defined by config file parameters. For instance, the command + +\begin{verbatim} +simplaret search kernel-generic +\end{verbatim} + +can return something like + +\begin{verbatim} +ROOT repository sarava, arch: i386, version: 11.0: kernel-generic-2.6.17.13-i486-1.tgz +ROOT repository sarava, arch: i386, version: 11.0: kernel-generic-2.6.18-i486-1.tgz +\end{verbatim} + +So the command + +\begin{verbatim} +simplaret install kernel-generic +\end{verbatim} + +will attempt to install the package "kernel-generic-2.6.17.13-i486-1.tgz" and not the file "kernel-generic-2.6.18-i486-1.tgz". If you want to force simplaret to get and specific package, use its complete file name: + +\begin{verbatim} +simplaret install kernel-generic-2.6.18-i486-1.tgz +\end{verbatim} + +If a package is already installed in the system, the --install option will try to upgrade it if the version or build number between the installed package and the one in the repository are different. So the command + +\begin{verbatim} +simplaret install simplepkg +\end{verbatim} + +updates simplepkg in the case there's a new version. To remove a package, type + +\begin{verbatim} +simplaret remove nome-do-pacote +\end{verbatim} + +That's just an alias for the standard removepkg command. + +Simplaret stores downloaded packages in a system folder that defaults to /var/simplaret. As you get more and more packages, simplaret will consume more space ir your disk. To erase your local repository folder, use the command + +\begin{verbatim} +simplaret purge +\end{verbatim} + +This will erase just the packages from the current arch and version. Details about how to erase the repository for different arch and version are in another session. + +You can also force simplaret to erase just old packages. The following command erases just packages older than six weeks or more: + +\begin{verbatim} +simplaret purge -w 3 +\end{verbatim} + +\section{Downloading patches and upgrading the system} + +Simplaret hasn't just about package installing and removal, it has two more important features: patches retrieval and application. Assuming that the patches repository of your slackware flavour is correctly configured (what should work with almost everyone with the default configuration), you can fetch the available patches using the command + +\begin{verbatim} +simplaret get-patches +\end{verbatim} + +If you don't just donwload but also apply those patches, use + +\begin{verbatim} +simplaret upgrade +\end{verbatim} + +\section{Working with more than one architecture and version} + +Until now we just looked what is the requirement for all package management system: package retrieval, installation, search, upgrade and dependency resolution. What makes simplaret different from another tools is the ability to deal with different architectures and versions and slackware installations. + +The features descibed in this section will just make sense after you read the next section, when we'll talk about multiple slackware installations and jails in the same computer. + +Suppose you're running Slackware (arch i386) bit wants to update the package list from Slamd64 version 11.0 (arch x86\_64). To do that, just type + +\begin{verbatim} +ARCH=x86_64 VERSION=11.0 simplaret update +\end{verbatim} + +This command grabs the Slamd64 package list without confliting in any way with the standard and already downloaded i386 Slackware package list. This doesn't happens because simplaret stores metadata from different archs and versions at different folders. + +Its optional to pass ARCH and VERSION environment variables to simplaret. If one or none of them was specified, simplaret uses the standar system value, obtained from the file /etc/slackware-version, or uses config parameters to do that. + +As an example, to search for a package in the arch powerpc (Slackintosh) version 11.0, just type + +\begin{verbatim} +ARCH=powerpc VERSION=11.0 simplaret search package-name +\end{verbatim} + +All command previously mentioned can work that way, except those that install or remove packages as its dangerous to mix packages from different archs and versions in the same system. + +\section{Working with multiple installations} + +The previously section mentions a feature that just makes sense in systems where there's more than one slackware-like installation using different archs and versions. + +Say you have a x86\_64 machine with three installed systems: + +\begin{enumerate} + \item Slamd64 11.0 at the root folder + \item Slackware 11.0 at /mnt/slackware-1 + \item Slackware 10.2 at /mnt/slackware-2 +\end{enumerate} + +In the case of package install or patch retrieval and application, simplaret supports the environment variable ROOT to specify which folder simplaret should look for a system. + +Then, to install a package at /mnt/slackware-1, just type + +\begin{verbatim} +ARCH=i386 VERSION=11.0 simplaret update +ROOT=/mnt/slackware-1 simplaret install package-name +\end{verbatim} + +The first command just updates the package list and the second makes simplepkg install the package with using /mnt/slackware-1 arch and version. If you want to do the same at /mnt/slackware-2, use the analogous command + +\begin{verbatim} +ARCH=i386 VERSION=10.2 simplaret update +ROOT=/mnt/slackware-2 simplaret install package-name +\end{verbatim} + +There's also a feature to make patch retrieval and application with just one command, using the file /etc/simplepkg/jailist. This file is used by simplepkg's mkjail script to store with jails you have on your system but is also used by simplaret to upgrade all jails with just one command. + +Considering that your box has the three previously mentioned slackware installation. Then, to add /mnt/slackware-1 and /mnt/slackware-2 in the automatic upgrade list, add the following lines in your /etc/simplepkg/jailist (without spaces): + +\begin{verbatim} +/mnt/slackware-1 +/mnt/slackware-2 +\end{verbatim} + +The root system doesn't need to be added in this file. Then, you can get the patches for all your three systems with the command + +\begin{verbatim} +simplaret get-patches +\end{verbatim} + +To get the patches and/or apply them in all jails (including the root system), use + +\begin{verbatim} +simplaret upgrade +\end{verbatim} + +This feature makes easier to keep all your installations always upgraded. + +\section{The repos.conf file} + +Now that we just talked about all simplaret features, its time to take a tour at its configuration files. The first one we'll say about is the repository definition file, /etc/simplepkg/repos.conf. + +If you don't mind to make an advanced simplaret usage, then probably you can just leave this section as the default config should work for almost all standard situations and you'll just need to edit repos.conf to change repository priorities. + +The repos.conf file contains one repository definition per line using the following syntax: + +\begin{verbatim} +TYPE[-ARCH][-VERSION]="name%URL" +\end{verbatim} + +The content in brackets are optional depending on the repository type as we'll see later in this section. The repository types supported by simplaret are: + +\subsection{PATCHES} + +PATCHES: used for repositories containing patches and which file metadata is the file FILE\_LIST instead the standard FILELIST.TXT; example: + +\begin{verbatim} +PATCHES-i386-11.0="sarava%http://slack.sarava.org/packages/slackware/slackware-11.0/patches/" +\end{verbatim} + +This defines a patches repository for arch i386 (official Slackware), version 11.0 and named as "sarava". + +Its optional to have a PATCHES definition in order to get patches: the ROOT repository definition just take care of that and you'll just need to use a PATCHES definition if you want to give precedence to some patches repository over all other definition types. + +\subsection{ROOT} + +ROOT: this type specifies the default slackware-like repository, where the content is sorted by version. An official slackware repository then is defined as + +\begin{verbatim} +ROOT-i386="tds%http://slackware.mirrors.tds.net/pub/slackware/" +\end{verbatim} + +ROOT repositories needs just the arch definition, a name and an URL. In the previous case, we have a ROOT repository called "tds". It doesn't need any version information as its already considers tha the content is sorted in folders like http://slackware.mirrors.tds.net/pub/slackware/slackware-10.2/ and http://slackware.mirrors.tds.net/pub/slackware/slackware-11.0/. + +\subsection{REPOS} + +REPOS: this repository type ir arch and version oriented, like + +\begin{verbatim} +REPOS-i386-11.0="sarava%http://slack.sarava.org/packages/slackware/slackware-11.0/" +\end{verbatim} + +In the above case, a repository called "sarava" is defined using arch i386 and version 11.0 with URL http://slack.sarava.org/packages/slackware/slackware-11.0/. This repository type is recommended when using non-official repositories. + +\subsection{NOARCH} + +NOARCH: the last type is used to define repositories where packages are arch and version independent, like + +\begin{verbatim} +NOARCH="sarava%http://slack.sarava.org/packages/noarch" +\end{verbatim} + +In any repository type, the supperted URL schemes are http://, ftp:// or file:// (for local repositories). + +\section{Repository order and precedence} + +As simplaret supports more than one repository definition for each type, arch or version, each definition has its own name. Definitions can have the same name just if they're dont use the same repository type and/or arch and version. + +There's also a priority rule between the repository types wich defines a precedence order. Repositories are searched according the following order: + +\begin{itemize} + \item PATCHES has the highest priority: if a package from a given arch and version is not found in the first (if existent) PATCHES definition, then the next one is searched until all PATCHES definitions are searched. + \item Then, the package is searched in all ROOT defintions in the order they appear at repos.conf. + \item The next searched repository type is REPOS in the specified arch an version, in the order they appear at repos.conf. + \item At last, NOARCH type is searched in the order they're defined. +\end{itemize} + +In the case you're issuing an upgrade or just geting patches, simplaret by default will just search in PATCHES and ROOT definitions. + +At REPOS and ROOT is also possible to specify its internal search order according its subfolders. + +\section{Configuration file simplepkg.conf} + +Simplaret also stores its configurations inside simplepkg's configuration file /etc/simplepkg/simplepkg.conf. This file is well commented and you should find there a description of all supported options. + +\section{But why use that?} + +You may ask why someone wishes to use such tool. + +Simplaret was written with a *x86 environment in mind, where lots of jails with different archs and versions are installed. Suppose a x86\_64 with the following chroots installed: + +\begin{itemize} + \item slamd64 11.0 + \item slackware 10.0 + \item slackware 11.0 with additional i686 packages + \item uSlack (i386 uClibc) +\end{itemize} + +Keep all this stuff update manually is really a headache. Simplaret just tries to make it trivial. + +\section{Additional information} + +Simplaret was written by Silvio Rhatto (rhatto at riseup.net) and is released under GPL license. The code can be obtained from the subversion repository: + +\begin{verbatim} +svn checkout svn://slack.sarava.org/simplepkg +\end{verbatim} + +Simplepkg's wiki is http://slack.sarava.org/trac/wiki/Simplepkg and its mailing list address is http://listas.sarava.org/wws/info/slack. + +\end{document} diff --git a/doc/simplaret-pt_BR.tex b/doc/simplaret-pt_BR.tex new file mode 100644 index 0000000..986dbb0 --- /dev/null +++ b/doc/simplaret-pt_BR.tex @@ -0,0 +1,376 @@ +\documentclass{article} +\usepackage[brazilian]{babel} +\usepackage[latin1]{inputenc} +\usepackage[dvips]{graphics} +\usepackage{hyperref} +\usepackage{html,makeid} + +\title{Simplaret: ferramenta para obtenção de pacotes} +\author{Silvio Rhatto} + +\begin{document}\label{start} +\maketitle + +\begin{abstract} +O \emph{simplaret} é a ferramenta do \htmladdnormallink{simplepkg}{http://slack.sarava.org/node/12} utilizada para obter pacotes de repositórios locais ou remotos. Com ele, você pode não só baixar pacotes do seu sistema \emph{slackware} como também pode baixar de qualquer versão ou arquitetura cujo repositório siga os \htmladdnormallink{Mirror Guidelines do Slackware}{http://www.slackware.com/getslack/mirroring_guidelines.txt}, permitindo que você gerencie facilmente todas as suas jaulas e instalações de Slackware, independentemente da arquitetura ou versão que elas utilizem. English version \htmladdnormallink{here}{/node/17}. + +Além da obtenção, o \emph{simplaret} ainda pode fazer a instalação, a remoção ou a atualização dos pacotes de um sistema e também das demais jaulas existentes numa máquina. O simplaret é totalmente não-intrusivo no sistema e roda sobre o pkgtool. +\end{abstract} + +\section{Obtendo e instalando} + +O \emph{simplaret} acompanha o \htmladdnormallink{simplepkg}{http://slack.sarava.org/node/12} e por isso sua instalação é feita baixando o pacote do simplepkg +em \htmladdnormallink{http://slack.sarava.org/packages/noarch/}{http://slack.sarava.org/packages/noarch/} e em seguida instalando-o com o comando + +\begin{verbatim} +installpkg simplepkg-VERSAO-noarch-BUILD.tgz +\end{verbatim} + +A partir daí você já pode utilizar o \emph{simplaret} para baixar pacotes dos repositórios padrão ou então alterar a lista de repositórios do arquivo \emph{/etc/simplepkg/repos.conf} ou a configuração do aplicativo pelo arquivo \emph{/etc/simplepkg/simplepkg.conf}. + +A configuração padrão de repositórios no simplaret se encontra em \emph{/etc/simplepkg/defaults/repos.conf}, mas não recomendamos você editá-la. Use, ao invés disso, o \emph{/etc/simplepkg/repos.conf} para sua configuração personalizada: se o simplaret encontrar esse arquivo, ele simplesmente ingorará as definições padrão de repositório. + +\section{Usando o simplaret} + +Em geral, como o \emph{simplaret} armazena as informações em pastas do sistema, algumas funcionalidades só estarão disponíveis quando o mesmo é rodado pelo superusuário do sistema. + +Antes de explorar todas as funcionalidades do \emph{simplaret}, é necessário atualizar a lista de pacotes para sua arquitetura e versão, o que pode ser feito com o comando + +\begin{verbatim} +simplaret --update +\end{verbatim} + +ou simplesmente + +\begin{verbatim} +simplaret update +\end{verbatim} + +já que o \emph{simplaret} suporta que suas opções básicas de linha de comando sejam passas precedidas por dois hífens ou não (\emph{--update} ou \emph{update}). + +Depois de atualizar a lista de pacotes, experimente buscar por um pacote com um comando do tipo + +\begin{verbatim} +simplaret search ekiga +\end{verbatim} + +O resultado pode ser algo do tipo + +\begin{verbatim} +REPOS repository sarava, arch: i386, version: 11.0: ekiga-2.0.5-i586-1rd.tgz +\end{verbatim} + +Como veremos adiante, "REPOS" significa o tipo de repositório, "sarava" é o nome do +repositório, "arch" mostra a arquitetura do pacote e do repositório (\emph{i386}, no caso) +e "version" a versão do repositório (\emph{11.0}, no caso). + +Para instalar esse pacote, basta o comando + +\begin{verbatim} +simplaret install ekiga +\end{verbatim} + +Por padrão, se o \emph{simplaret} encontrar no repositório um arquivo \emph{slack-required} referente ao pacote en questão (ou seja, um arquivo \emph{ekiga.slack-required} na mesma pasta que o pacote do ekiga, neste caso), então o \emph{simplaret} tentará instalar todos os requisitos contidos nesse slack-required, caso já não estejam instalados no sistema. Essa resolução de dependências automática pode, no entanto, ser desabilitada através de um parâmetro de configuração, como veremos a seguir. + +Se você apenas quiser baixar o pacote, digite apenas + +\begin{verbatim} +simplaret get ekiga +\end{verbatim} + +No caso do \emph{simplaret} encontrar mais de um pacote com o mesmo nome, ele baixará na ordem que a opção "search" listá-los, sendo que essa precedência é definida de acordo com a ordem em que os repositórios estão listados no arquivo de configuração. Por exemplo, o comando + +\begin{verbatim} +simplaret search kernel-generic +\end{verbatim} + +pode retornar algo como + +\begin{verbatim} +ROOT repository sarava, arch: i386, version: 11.0: kernel-generic-2.6.17.13-i486-1.tgz +ROOT repository sarava, arch: i386, version: 11.0: kernel-generic-2.6.18-i486-1.tgz +\end{verbatim} + +Assim, o comando + +\begin{verbatim} +simplaret install kernel-generic +\end{verbatim} + +instalará o pacote "kernel-generic-2.6.17.13-i486-1.tgz" ao invés do pacote "kernel-generic-2.6.18-i486-1.tgz". Caso você queira forçar a instalação do segundo pacote, basta especificá-lo com o nome completo: + +\begin{verbatim} +simplaret install kernel-generic-2.6.18-i486-1.tgz +\end{verbatim} + +Se um pacote já estiver instalado no sistema, a opção install fará o upgrade do mesmo, caso a versão ou o build number do pacote presente no repositório for diferente da instalada no sistema. Assim, o comando + +\begin{verbatim} +simplaret install simplepkg +\end{verbatim} + +atualiza o simplepkg caso haja uma nova versão disponível nalgum repositório. + +Para remover um pacote, digite + +\begin{verbatim} +simplaret remove nome-do-pacote +\end{verbatim} + +o que na verdade é apenas uma chamada indireta ao removepkg. + +O \emph{simplaret} armazena pacotes baixados de repositórios numa pasta local do sistema, que por padrão é \emph{/var/simplaret}. Conforme você vai baixando e instalando pacotes, essa pasta tende a crescer e ocupar muito espaço. Para apagar os pacotes, basta usar o comando + +\begin{verbatim} +simplaret purge +\end{verbatim} + +Isso apagará apenas os pacotes da arquitetura e versão usadas atualmente. Detalhes de como apagar os pacotes de todas a arquiteturas e versões serão dados numa seção seguinte. + +Você também pode forçar o \emph{simplaret} a apagar apenas pacotes antigos. O comando a seguir apaga apenas os pacotes baixados a três semanas ou mais (ou seja, os pacotes baixados a menos de três semanas continuam armazenados): + +\begin{verbatim} +simplaret purge -w 3 +\end{verbatim} + +\section{Baixando patches e atualizando o sistema} + +O \emph{simplaret} possui, além do básico do gerenciamento de pacotes, duas funcionalidades adicionais: a obtenção e a aplicação de patches (pacotes contendo atualizações e correções de segurança). + +Assumindo que os repositórios contendo patches para sua distribuição do tipo Slackware estejam corretamente configurados, o que ocorre com a configuração padrão que acompanha o \emph{simplepkg} e que veremos a seguir como alterá-la, você pode baixar os patches disponíveis para o seu sistema com o comando + +\begin{verbatim} +simplaret get-patches +\end{verbatim} + +Se você quiser não só baixar mas também atualizar seu sistema, isto é, fazer um upgrade com os patches disponíveis, use + +\begin{verbatim} +simplaret upgrade +\end{verbatim} + +\section{Trabalhando com múltiplas arquiteturas e versões} + +Até aqui vimos apenas o que é a obrigação de qualquer sistema de gerenciamento de pacotes possuir: obtenção de pacotes, instalação, busca e atualização do sistema. O que diferencia o \emph{simplaret} das outras ferramentas, além do esquema de resolução de dependências, é sua capacidade de lidar simultaneamente com múltiplas arquiteturas, versões e até instalações de sistemas do tipo Slackware. + +O uso dos seguintes comandos só fará sentido à luz da próxima seção, onde trataremos a respeito de múltiplas instalações e jaulas num mesmo computador, porém é um pré-requisito para entendê-la. + +Supondo que você esteja rodando Slackware (arquitetura \emph{i386}) mas que queira atualizar a lista de pacotes do sistema Slamd64 versão \emph{11.0} (arquitetura \emph{x86\_64}), basta usar o comando + +\begin{verbatim} +ARCH=x86_64 VERSION=11.0 simplaret update +\end{verbatim} + +Esse comando baixará a lista de pacotes para o Slamd64 sem conflitar de nenhuma forma com a lista e os pacotes já baixados para o Slackware. Isso acontece porque o \emph{simplaret} armazena as informações e os pacotes de cada repositório em pastas próprias, organizadas de acordo com a arquitetura e versão. + +Passar as variaveis \emph{ARCH} e \emph{VERSION} para o \emph{simplaret} é opcional. Se qualquer uma delas não foi especificada, o \emph{simplaret} utilizará o valor padrão do seu sistema, usualmente obtido do arquivo \emph{/etc/slackware-version} ou então especificada através do arquivo de configuração do simplepkg. + +Por exemplo, para pesquisar por um pacote da arquitetura powerpc (distribuição Slackintosh) na versão \emph{11.0}, basta o comando + +\begin{verbatim} +ARCH=powerpc VERSION=11.0 simplaret search nome-do-pacote +\end{verbatim} + +Todos os comandos apresentados anteriormente funcionarão dessa maneira, à exceção daqueles que instalam ou fazer a atualização de pacotes, já que em geral é destrutivo misturar pacotes de arquiteturas e versões diferentes num mesmo sistema. + +\section{Trabalhando com múltiplas instalações} + +A funcionalidade apresentada na seção anterior só faz sentido quando existirem sistemas, jaulas e/ou vservers instalados num mesmo computador. + +Suponha que você possua uma máquina \emph{x86\_64} com três sistemas instalados: + + - Slamd64 \emph{11.0} na raíz + - Slackware \emph{11.0} em \emph{/mnt/slackware-1} + - Slackware \emph{10.2} em \emph{/mnt/slackware-2} + +No caso da instalação de pacotes, da obtenção e aplicação de atualizações, o \emph{simplaret} suporta a variável de ambiente ROOT para especificar qual é a pasta na qual o \emph{simplaret} deve buscar o sistema. + +Para instalar um pacote no Slackware contido em /mnt/slackware-1, basta usar os comandos + +\begin{verbatim} +ARCH=i386 VERSION=11.0 simplaret update +ROOT=/mnt/slackware-1 simplaret install nome-do-pacote +\end{verbatim} + +O primeiro comando apenas atualiza a lista de pacotes e o segundo faz com que o \emph{simplaret} baixe o pacote da arquitetura e versão do sistema presente em \emph{/mnt/slackware-1} bem como efetue sua instalação. + +Para o caso da instalação em \emph{/mnt/slackware-2}, o uso é análogo: + +\begin{verbatim} +ARCH=i386 VERSION=10.2 simplaret update +ROOT=/mnt/slackware-2 simplaret install nome-do-pacote +\end{verbatim} + +Existe ainda uma facilidade para que a obtenção e aplicação de atualizações seja feita de forma única, através do arquivo \emph{/etc/simplepkg/jailist}. Esse arquivo serve, além de outros propósitos descritos na documentação do simplepkg, para que o \emph{simplaret} saiba de antemão quais são as instalações de sistema do tipo Slackware presentes numa máquina, além da instalação principal na raíz do sistema. + +Considerando que a máquina possua as três instalações citadas no início deste tópico, a atualização automática das mesmas pode ser feita quando o arquivo \emph{/etc/simplepkg/jailist} contiver as seguintes linhas (sem espaços no início de cada uma): + +\begin{verbatim} +/mnt/slackware-1 +/mnt/slackware-2 +\end{verbatim} + +O sistema principal, contido na raíz do sistema, não precisa estar listado nesse arquivo. Se todas as suas instalações de sistema do tipo Slackware estiverem constando corretamente no \emph{/etc/simplepkg/jailist}, o seguinte comando baixará as atualizações disponíveis para todas elas, incluindo o sistema contido na raíz: + +\begin{verbatim} +simplaret get-patches +\end{verbatim} + +Analogamente, o seguinte comando baixará e/ou aplicará todas as atualizações disponíveis em todas as instalações, incluindo o sistema contido na raíz: + +\begin{verbatim} +simplaret upgrade +\end{verbatim} + +Desse modo, o gerenciamento de pacotes numa máquina que contenha mais de uma instalação do tipo Slackware fica unificada e consequentemente simplificada. + +\section{O arquivo repos.conf} + +Agora que o comportamento do \emph{simplaret} foi delineado, é importante descrever o arquivo de definição de repositórios, o \emph{/etc/simplepkg/repos.conf}. Se você não pretende fazer um uso avançado do \emph{simplaret}, provavelmente pode deixar de ler esta e a próxima seção, já que para o uso corriqueiro do \emph{simplaret} você provavelmente não precisará alterar seu \emph{repos.conf}, a não ser que queira mudar o espelho de download dos seus pacotes ou montar um esquema avançado para a escolha e priorização de repositórios. + +O arquivo \emph{/etc/simplepkg/repos.conf} contém uma definição de repositório por linha e a sintaxe de cada uma delas é: + +\begin{verbatim} +TIPO[-ARQUITETURA][-VERSAO]="nome%URL" +\end{verbatim} + +O conteúdo demarcado por colchetes é opcional dependendo do tipo de repositório, como veremos a seguir. Os tipos de repositório aceitos pelo \emph{simplaret} são: + +\subsection{PATCHES} + +\emph{PATCHES}: definição para repositórios que contenham patches (pacotes de atualização) e cuja lista de arquivos é \emph{FILE\_LIST} e não \emph{FILELIST.TXT}; exemplo: + +\begin{verbatim} +PATCHES-i386-11.0="sarava%http://slack.sarava.org/packages/slackware/slackware-11.0/patches/" +\end{verbatim} + +No caso da definição acima, temos um repositório de patches para a arquitetura \emph{i386} (distribuição Slackware), versão \emph{11.0} e o nome dado ao repositório é "sarava". + +Possuir uma definição do tipo \emph{PATCHES} é opcional para ter acesso às atualizações: a definição de repositório \emph{ROOT}, que veremos em seguida, já lida com patches: o tipo de repositório \emph{PATCHES} serve apenas se você quiser utilizar algum repositório não-oficial como fonte de patches prioritária, já que repositório \emph{PATCHES} são pesquisados pelo \emph{simplaret} antes de qualquer outro. + +Em resumo, se você não tiver um bom motivo para usar esse tipo de repositório, evite-o. + +\subsection{ROOT} + +\emph{ROOT}: são tipos de repositórios cujo conteúdo está dividido por versão. O exemplo tradicional deste caso é o próprio repositório oficial das distribuições: + +\begin{verbatim} +ROOT-i386="tds%http://slackware.mirrors.tds.net/pub/slackware/" +\end{verbatim} + +Repositórios \emph{ROOT} necessitam apenas de uma definição de arquitetura, um nome e uma URL. No caso acima, temos a definição de repositório \emph{ROOT} de nome "tds", ou seja, não há definição de versão, já que o \emph{simplaret} considerará que a versão desejada está numa subpasta dessa URL. Ou seja, definições ROOT implicam que as pastas contendo pacotes de cada versão estejam bem separadas, ou seja, pastas como http://slackware.mirrors.tds.net/pub/slackware/slackware-10.2/ e http://slackware.mirrors.tds.net/pub/slackware/slackware-11.0/. + +\subsection{REPOS} + +\emph{REPOS}: este tipo de repositório é orientado a arquitetura e versão, como por exemplo + +\begin{verbatim} +REPOS-i386-11.0="sarava%http://slack.sarava.org/packages/slackware/slackware-11.0/" +\end{verbatim} + +No caso acima, um repositório de nome "sarava" é definido para a arquitetura \emph{i386} e versão \emph{11.0} com a URL http://slack.sarava.org/packages/slackware/slackware-11.0/. Esse tipo de definição é recomendado para repositórios não-oficiais. + +\subsection{NOARCH} + +\emph{NOARCH}: o último tipo de definição é usado para repositórios cujos pacotes são independentes de arquitetura e versão da distribuição. Como exemplo temos um repositório do Projeto Slack: + +\begin{verbatim} +NOARCH="sarava%http://slack.sarava.org/packages/noarch" +\end{verbatim} + +Em qualquer tipo de repositório, a URL pode ser do tipo http://, ftp:// ou file:// (para repositórios locais). + +\section{Ordem e precedência em repositórios} + +Como podem haver mais de uma definição de repositório para cada tipo, versão e/ou arquitetura, as mesmas são diferenciadas de acordo com o nome. Definições de repositório podem ter nomes idênticos, desde que se refiram a tipo de repositório e/ou arquitetura e versão diferentes. + +Existe ainda uma prioridade dentre tipos de repositório e ordens de precedência. Numa pesquisa, repositórios são pesquisados de acordo com a seguinte ordem: + +\begin{enumerate} +\item \emph{PATCHES} tem prioridade mais alta: caso um pacote de uma dada arquitetura e versão não seja encontrado no primeiro repositório \emph{PATCHES} do \emph{repos.conf}, o próximo repositório definido na ordem em que ele aparece no arquivo é pesquisado, e assim por diante. +\item Em seguida, pacotes são procurados nas definições \emph{ROOT} da arquitetura em questão, na ordem em que aparecem no \emph{repos.conf}. +\item Depois, são os pacotes de repositórios \emph{REPOS} daquela arquitetura e versão são pesquisados, na ordem em que aparecem no repos.conf. +\item Por fim, repositórios \emph{NOARCH} são pesquisados, na ordem em que são definidos. +\end{enumerate} + +Em resumo, o \emph{simplaret} tem uma ordem de precedência e execução de repositórios e para busca e obtenção de pacotes: pacotes são exibidos de acordo com a ordem e precedência descritas acima. No caso da ontenção de pacotes, o primeiro repositório que possuí-lo será utilizado, isto é, caso o pacote não for solicitado explicitamente com seu nome de arquivo completo mas sim apenas com seu nome. + +No caso da obtenção de patches, por padrão apenas repositórios do tipo \emph{PATCHES} e \emph{ROOT} são pesquisados, a não ser que isso seja configurado como contrário. + +Em repositórios do tipo \emph{REPOS} e \emph{ROOT} ainda é possível, através de parâmetros de configuração, explicitar a ordem de pastas que são pesquisadas dentro dos repositórios, algo que veremos a seguir e facilita no caso do usuário estar interessado em dar prioridade para aplicativos em fase de testes (usualmente armazenados na pasta testing/) ou pacotes antigos (pasture). + +\section{Parâmetros de configuração do simplepkg.conf} + +Nesta seção os parâmetros do arquivo de configuração \emph{/etc/simplepkg/simplepkg.conf} relevantes ao \emph{simplaret} estão descritos. Para uma lista completa de todos os parâmetros disponíveis, consulte o simplepkg.conf contido no pacote do simplepkg. Aqui estão descritos apenas os principais, que são: + +\begin{itemize} +\item \emph{STORAGE}: local de armazenameto dos pacotes baixados e das informações de repositório. O valor padrão é \emph{/var/simplaret/packages}. + +\item \emph{PATCHES\_DIR}: local de armazenamento de pacotes que são patches (atualizações), isto é, o local de armazenamento de pacotes de repositórios do tipo PATCHES (e eventualmente de patches encontrados em repositórios do tipo \emph{ROOT}, como veremos a seguir). O valor padrão é \emph{/var/simplaret/patches}. + +\item \emph{SIMPLARET\_DOWNLOAD\_FROM\_NEXT\_REPO}: indica se o \emph{simplaret} deve tentar baixar um pacote do próximo repositório (caso exista) quando o download do repositório atual tiver falhado. Valores possíveis são "1" ou "yes" para habilitar a opção (que é o comportamento padrão) ou "0" ou "no" para desabilitá-la. + +\item \emph{SIMPLARET\_PURGE\_PATCHES}: indica se o conteúdo da pasta de patches também deve ser apagado quando o comando "simplaret --purge" é chamado. Use "yes" ou "1" para habilitar e "no" ou "0" para desabilitar. O valor padrão é "1". + +\item \emph{SIMPLARET\_PURGE\_WEEKS}: controla o número de semanas a partir do qual o \emph{simplaret} irá apagar pacotes quando chamado com o comando "simplaret --purge", o que é equivalente a usar o comando "simplaret --purge -w N". O valor padrão é "3". Para desabilitar essa opção, atribua o valor "0". + +\item \emph{PASSIVE\_FTP}: Indica se o \emph{simplaret} deve fazer as transferências de FTP no modo passivo. O valor padrão é "1" (habilitado). + +\item \emph{HTTP\_TOOL}: especifica qual a ferramenta para obtenção de arquivos via protocolo HTTP. As opções disponíveis são "curl" e "wget", sendo que a opção padrão é "curl". + +\item \emph{FTP\_TOOL}: especifica qual a ferramenta para obtenção de arquivos via protocolo FTP. As opções disponíveis são "curl", "wget" e "ncftpget", sendo que a opção padrão é "curl". + +\item \emph{CONNECT\_TIMEOUT}: tempo máximo de espera para uma conexão de rede, dado em segundos. O valor padrão é "20". + +\item \emph{ROOT\_PRIORITY}: especifica a ordem de prioridades das pastas de repositórios do tipo \emph{ROOT} numa pesquisa. O valor padrão é "patches slackware extra testing pasture", indicando que a pasta de patches tem precedência sobre todas as outras no repositório, sendo seguida pela pasta slackware e depois pelas extra, testing e pasture. Como podem existir nomes de pacotes idênticos nessas pastas, o estabelecimento de uma ordem se faz necessária. + +\item \emph{REPOS\_PRIORITY}: da mesma forma como repositorios \emph{ROOT} necessitam de uma prioridade de pesquisa em pastas, este parâmetro de configuração especifica a prioridade de pastas em repositórios do tipo \emph{REPOS}. O valor padrão é "patches slackware extra testing pasture". + +\item \emph{SIGNATURE\_CHECKING}: indica se o \emph{simplaret} deve checar pela assinatura dos pacotes baixados, caso ela esteja disponível. Você deve ter a chave pública do distribuidor dos pacotes no seu chaveiro. O valor padrão é "0" (desabilitado). + +\item \emph{DEPENDENCY\_CHECKING}: indica se o \emph{simplaret} deve trabalhar com a resuloção de dependências caso ele encontre, no repositório, um arquivo slack-required correspondente ao pacote que está sendo instalado. O valor padrão é "1" (habilitado). + +\item \emph{DOWNLOAD\_EVEN\_APPLIED\_PATCHES}: indica de o \emph{simplaret} deve baixar todos os patches disponíveis a uma dada instalação de sistema do tipo Slackware, mesmo que os mesmo já se encontrem aplicados. Esta opção é útil se você quiser manter uma cópia local das atualizações existentes para seu sistema. O valor padrão é "0" (desabilitado). + +\item \emph{CONSIDER\_ALL\_PACKAGES\_AS\_PATCHES}: especifica se o \emph{simplaret} deve, durante a obtenção de pacotes de atualização, procurar por atualizações também nos tipos de repositórios \emph{REPOS} e \emph{NOARCH}. Com essa opção, o \emph{simplaret} faz uma pesquisa pelo pacote e, se sua versão ou buildnumber da primeira ocorrência não bater com as do pacote atualmente instalado, ele baixa e o aplica, mesmo que seja um pacote de repositórios do tipo \emph{REPOS} ou \emph{NOARCH}. O valor padrão é "0" (desabilitado). O uso dessa opção não é muito recomendado por poder causar confusão e deixar o \emph{simplaret} mais lento, mas pode ser útil caso você esteja usando um repositório não-oficial que sempre atualiza seus pacotes. + +\item \emph{STORE\_ROOT\_PATCHES\_ON\_PATCHES\_DIR}: controla se o \emph{simplaret} deve armazenar os patches baixados de repositórios do tipo \emph{ROOT} na mesma pasta de armazenamento de patches provenientes de repositórios do tipo \emph{PATCHES}. É uma opção útil apenas se você quiser manter todos os patches de repositórios \emph{ROOT} e \emph{PATCHES} num mesmo local. O valor padrão é "0" (desabilitado). +\end{itemize} + +Vale lembrar que todas as opções booleanas (isto é, que podem ser apenas habilitadas ou desabilitadas) +do simplepkg.conf tem os seguintes valores permitidos: "1" e "yes" para habilitado e "0" ou "no" para +desabilitado. + +\section{Mas pra quê serve isso?} + +Você pode estar se perguntando: para que mais um gerenciador de pacotes para o Slackware e quem utilizaria +uma ferramenta que baixa pacotes de várias arquiteturas? + +O \emph{simplaret} foi escrito tendo em mente um ambiente \emph{*86} onde várias \emph{jaulas} de diferentes arquiteturas estão instaladas. Suponha por exemplo uma máquina \emph{x86\_64} que possua as seguintes jaulas: + +\begin{itemize} + \item slamd64 \emph{11.0} + \item slackware \emph{11.0} + \item slackware \emph{11.0} com pacotes adicionais em \emph{i686} + \item \htmladdnormallink{uSlack}{http://gnuden.sarava.org} (\emph{uClibc para i386}) +\end{itemize} + +O condenado/a em questão que roda todas essas jaulas, pelos mais diversos motivos, pode ter uma grande dor de cabeça para manter os pacotes em ordem de forma manual. Com o \emph{simplaret} e eventualmente com o \emph{simplepkg}, a tarefa se torna trivial. + +Além disso, as inúmeras novas tecnologias de virtualização poderão necessitar de um sistema de gerenciamento de pacotes que trabalha simultaneamente com múltiplas arquiteturas e versões. + +Mesmo que você possua apenas um único sistema do tipo Slackware em seu computador ou trabalhe apenas com uma única arquitetura e/ou versão, o \emph{simplaret} possui todas as funcionalidades necessárias para facilitar seu dia-a-dia de gerenciamento de pacotes. + +\section{Mais informações} + +O \emph{simplaret} foi escrito por Silvio Rhatto (rhatto at riseup.net) e é disponibilizado dentro do pacote do +simplepkg e sob a licença GPL. Para obter o código fonte, digite + +\begin{verbatim} +svn checkout http://slack.sarava.org/simplepkg +\end{verbatim} + +O wiki de desenvolvimento é \htmladdnormallink{http://slack.sarava.org/trac/wiki/Simplepkg}{http://slack.sarava.org/trac/wiki/Simplepkg} e o endereço da lista de discussão utilizada para discussões sobre \emph{simplaret}, simplepkg ou mesmo distribuições e pacotes do tipo Slackware é \htmladdnormallink{http://listas.sarava.org/wws/info/slack}{http://listas.sarava.org/wws/info/slack}. + +\end{document} + diff --git a/doc/simplepkg-en.tex b/doc/simplepkg-en.tex new file mode 100644 index 0000000..4d32876 --- /dev/null +++ b/doc/simplepkg-en.tex @@ -0,0 +1,390 @@ +\documentclass{article} +\usepackage[brazilian]{babel} +\usepackage[latin1]{inputenc} +\usepackage[dvips]{graphics} +\usepackage{hyperref} +\usepackage{html,makeid} + +\title{Simplepkg: installation manager and packaging system} +\author{Silvio Rhatto} + +\begin{document}\label{start} +\maketitle + +\begin{abstract} +Simplepkg is a non-intrusive management system running on top of pkgtool made of a set of scripts which helps the sysadmin and developing cycles of an slackware system. It can be used to create packages and repositories as long as the operational system installation and config file change tracking. Portuguese documentation \htmladdnormallink{here}{/simplepkg}. +\end{abstract} + +\section{Description} + +All GNU/Linux distributions comes with a well developed packaging system. The question now is how pratical is the way to install, configure and control any changes in a system. + +As an example, suppose you should keep a list of about 200 slackware machines, some of them used as desktops, others as mail or webservers. If you lost some hardrives or usually need to re-install or update some of those boxes. + +Using the slackware installation cd and configuring by hand all the time you got a crash is a time loss activity and you'll never know if something remained missconfigured. An alternative is to keep a complete backup of a machine or some parts of the tree, but for a large number of different boxes this procedure costs a lots of resources. + +Simplepkg offers an alternative sollution for this and other problems related to installation management, allowing you to keep templates of each machine and install a custom slackware system with just one or a few commands. Creating and upgrading chroot and vservers is easy with simplepkg. + +Package and installation management is not everything simplepkg can do. It can also be used to create vservers, create packages and store system configuration files in a subversion repository. + +Simplepkg works with any (official or not) slackware port that follows the minimum system guidelines. + +\section{Architecture} + +Simplepkg is a set of scripts wrote in the KISS philosophy. Its a pretty simple system, composed by the following commands: + +\begin{itemize} + \item mkjail: build a slackware jail/installation in a folder + \item templatepkg: create or update a package list of an installation template + \item lspkg: show installed packages and its contents + \item jail-commit: update all configuration files of a template + \item jail-update: jail-commit counterpart + \item rebuildpkg: rebuild a package based on its /var/log/packages entry + \item simplaret: package retrieval tool + \item createpkg: donwload, compile and package creation script + \item repos: creates and manages binary repositories + \item mkbuild: app to build slackware build scripts +\end{itemize} + +\section{Installation} + +The latest version of simplepkg is locate at \htmladdnormallink{http://slack.sarava.org/packages/noarch/}{http://slack.sarava.org/packages/noarch/}. Install it with the usual way: + +\begin{verbatim} +installpkg simplepkg-VERSION-noarch-BUILD.tgz +\end{verbatim} + +\section{Simplepkg usage} + +The three main simplepkg uses are: + +\begin{itemize} + \item Package managemen + \item Jail/installation creation and management + \item Package creation +\end{itemize} + +Package management is made with simplaret app, whose behaviour is detailed in its own document. The following sections will only show how simplepkg can be used to manage jails and template and create packages. + +\section{Creating templates} + +Initially, simplepkg was built to help slackware install automation. To do that, it uses installation templates -- lists of installed packages, post-installation scripts and config files -- allowing the creation of installation profiles that can be used for system replication in other partition or even custom chroot building. + +Template creation is done with "templatepkg" script. To create a template called "my-slackware" containig the installed package list of your slackware installation, just type + +\begin{verbatim} +templatepkg -c my-slackware +\end{verbatim} + +The -c (or --create) flag tells templatepkg to create the /etc/simplepkg/templates/my-slackware folder with the following components: + +\begin{itemize} + \item /etc/simplepkg/templates/my-slackware/my-slackware.d: template config files + \item /etc/simplepkg/templates/my-slackware/my-slackware.s: post-installation scripts + \item /etc/simplepkg/templates/my-slackware/my-slackware.perms: metadata for config files + \item /etc/simplepkg/templates/my-slackware/my-slackware.template: installaed package list +\end{itemize} + +This four components are enough to store all slackware installation characteristics: the package list controls with applications are installed, the config file folder can contain all desired configurations for any installed application and the post-installation scripts take care of all procedures that should be executed exactly after the system installation. The my-slackware.perms file contains metadata for the saved config files, i.e, permission and ownership. + +If you want to build a template from a installation placed in another folder or partition thats not your current root dir, just type something like + +\begin{verbatim} +templatepkg -c my-slackware /mnt/slackware +\end{verbatim} + +where /mnt/slackware is the place where this alternative system is installed. After created, the template will contain just the installed package list or that folder. As the folder /var/log/packages of your installation doesn't keep information about the package installation order, its recommended that you manually edit the template's package list. To do that, just type + +\begin{verbatim} +templatepkg -e my-slackware +\end{verbatim} + +To add configuration files inside the template, type something like + +\begin{verbatim} +templatepkg -a my-slackware /etc/hosts +\end{verbatim} + +This should add /etc/hosts file to "my-slackware" template. Beyond just automatically copy the file when you install a new system using this template, simplepkg can also take care of every change that /etc/hosts can suffer on your system, such as file content or permission and ownership change. If you're also storing your templates in a subversion repository, you'll be able to track all changes it ever had. + +WARNING: avoid the storage in a template of config files that contains important security information such as passwords or secret keys. The prefered place to put such stuff is a secured backup. + +\section{Creating jails and replicating installations} + +As long as your template was created and populated with the package list, configuration files and post-installation scripts (what will be treated in another section), your can replicate your slackware installation as simpler than typing the following command: + +\begin{verbatim} +mkjail jail my-slackware +\end{verbatim} + +This creates a fresh slackware tree at /vservers/jail with all packages listed in the template "my-slackware" and all saved config files. The package installation is made by simplaret app, that should be properly configured. The standard simplaret configuration should work for most situations. + +If you want to install your jail in a place other than /vservers (this standard location can be changed through simpleokg config file), say /mnt/hda2, just use something like that: + +\begin{verbatim} +ROOT=/mnt mkjail hda2 my-slackware +\end{verbatim} + +The above command does exactly what you think: installs slackware in /mnt/hda2 with exactly the same packages you have on your system, replacing the need of the slackware installer! + +In case no template specified, mkjail uses the one stored /etc/simplepkg/defaults, if exists. Simplepkg already came if some pre-built templates at /etc/simplepkg/defaults/templates. + +\section{Post-installation scripts} + +Optionally, its possible to keep post-installation scripts inside a template. Such scripts are executed by mkjail exactly after a jail is installed and the template config files copied. To create or edit a post-installation script, just type + +\begin{verbatim} +templatepkg -b my-slackware script-name.sh +\end{verbatim} + +This adds the script-name.sh at "my-slackware" template. Mkjail passes two command line arguments to a post-install script: the upward folder and the jail's name ("/mnt" and "hda2" from our previous example). Then, an example script is something like that: + +\begin{verbatim} +#!/bin/bash +chroot $1/$2/ sbin/ldconfig +\end{verbatim} + +\section{Listing template contents} + +To list available templates or the template content, use commands such as + +\begin{verbatim} +templatepkg -l +templatepkg -l my-slackware +\end{verbatim} + +\section{Removing files from a template} + +As you did to add files, you can easily remove then from a template, using a comand such as + +\begin{verbatim} +templatepkg -d my-slackware /etc/hosts +\end{verbatim} + +This removes the file /etc/hosts from "my-slackware" template. + +\section{Removing a template} + +To remove a template, just type + +\begin{verbatim} +templatepkg -r my-slackware +\end{verbatim} + +\section{Updating a template} + +Now that we just talked about creating templates and jails, its time to cover another application, this time used to keep a template always updated. Jail-commit is a script that copies all config file changes (content, permissions and ownership) from a installation to a simplepkg template. + +For instance, if one wants to copy all changes from /mnt/hda2 jail into "my-slackware" template, he or she just needs to type the following command: + +\begin{verbatim} +jail-commit /mnt/hda2 my-slackware +\end{verbatim} + +Not just the package list from "my-slackware" template is updated according the installed packages from /mnt/hda2/var/log/packages: all config files from "my-slackware" template are compared it the ones from the jail and in case of any difference they're copied from the jail back to the template. Permissions and file ownership commit into the template works at the same way. + +Jail-commit allows that a template to being kept always updated and mirroring the actual configuration of an installed system. But if you want just to commit into the template just the installed package list, simply type + +\begin{verbatim} +templatepkg -u my-template +\end{verbatim} + +To make life even easier, there's also a feature of keeping a list of all installed slackware system in the box in the file /etc/simplepkg/jailist. This file, despite its use by simplaret (what is described in its own text), allow jail-commit to run with no arguments. + +Suppose you have three slackware installations: the root system and two more: + +\begin{itemize} + \item /mnt/slackware-1 using "slackware-1" template + \item /mnt/slackware-2 using "slackware-2" template +\end{itemize} + +If your /etc/simplepkg/jailist has the following lines: + +\begin{verbatim} +/mnt/slackware-1 +/mnt/slackware-2 +\end{verbatim} + +then the command + +\begin{verbatim} +jail-commit +\end{verbatim} + +will update both "slackware-1" and "slackware-2" templates according, respectivelly, the contents of /mnt/slackware-1 and /mnt/slackware-2. If you also have a template called "main", then jail-commit will sync the contents of your root system with that template. + +You can even add the following line at root's crontab + +\begin{verbatim} +20 4 * * * jail-commit +\end{verbatim} + +so all your templates get updated everyday. If your system is configured to send emails, then crontab's jail-commit output you give a summary of yesterday changes your system suffered, both config file changes and package additions and removals. + +\section{Restoring changes in a jail} + +The opposite operation of jail-commit also is possible: suppose you edited some config files in your system but suddenly wants to go back and copy all config files from a template to your jail. To do that, just use the command + +\begin{verbatim} +jail-update /mnt/hda2 my-slackware +\end{verbatim} + +\section{Storing templates inside a Subversion repository} + +In order to increase once more the control and flexibility of template contents, simplepkg can also handle templates inside a subversion repository. To do that, edit first the config gile /etc/simplepkg/simplepkg.conf and set the parameter TEMPLATES\_UNDER\_SVN to "yes". + +Then, create a fresh subversion repository to keep your templates with a command like that: + +\begin{verbatim} +svnadmin create /var/svn/simplepkg --fs-type fsfs +\end{verbatim} + +Then, you just need to import your templates with + +\begin{verbatim} +templatepkg -e file:///var/svn/simplepkg +\end{verbatim} + +From now jail-commit will commit automatically any template changes to the svn repository. If, in the other hand, you wish to grab the changes from the svn repository to your local copy, use + +\begin{verbatim} +templatepkg -s +\end{verbatim} + +In case you want to import a template folder from an existing repository, use + +\begin{verbatim} +templatepkg -i file:///var/svn/simplepkg +\end{verbatim} + +where file:///var/svn/simplepkg is the repository path. + +\section{Upgrading jails} + +Jail and installed system upgrading is done through simplaret and also supports /etc/simplepkg/jailist file. +For more info on how it works, take a look at simplaret own documentation. + +\section{Different archs and versions} + +Simplepkg was idealized to permit a template to create jails from any architecture and version of a slackware-like system. Upgrading tasks also are unified. This feature just works if you use simplaret and not swaret as the package retrieval tool. + +As another example, to create an slack 10.1 installation (assuming your /etc/simplepkg/repos.conf with the right configuration), just type + +\begin{verbatim} +VERSION=10.1 mkjail my-jail server-template +\end{verbatim} + +Different archs can be used too. If you have a x86\_64 system and wants to install a slack 10.2 in a partition, try something like + +\begin{verbatim} +ARCH=i386 VERSION=10.2 ROOT=/mnt mkjail hda2 my-slackware +\end{verbatim} + +Note that the templates are arch and version independent, as they just contain package names, configuration files and scripts. For this reason, the commands templatepkg, metapkg, lspkg and jail-update can be used normaly. + +\section{Creating a package from a template} + +If, for any reason, you wish to build a package from an existing template, try the command + +\begin{verbatim} +templatepkg -p template-name +\end{verbatim} + +Although that should work smoothly, its not the recommended behaviour, as simplepkg was designed to deal easily with templates and repositories. + +\section{Building packages} + +Until now, we just showed simplepkg applications used to manage installations and packages. But simplepkg can also create packages using createpkg script: it downloads, builds and packages software that has an available script from a SlackBuild in a repository, working like a slackware ports system. + +Createpkg works with any SlackBuild repository but works better and is well integrated if they are compliant with the standards from http://slack.sarava.org/trac/wiki/SlackBuilds. + +Specifically, createpkg was built to use slackbuilds from http://slack.sarava.org/slackbuilds through a subversion repository. + +To fetch all scripts from slack.sarava.org, type + +\begin{verbatim} +createpkg --sync +\end{verbatim} + +Then, you can list all available script using + +\begin{verbatim} +createpkg --list +\end{verbatim} + +To search for a script, use something like + +\begin{verbatim} +createpkg --search latex2html +\end{verbatim} + +This searches for a SlackBuild for the program "latex2html". If you want to build that package, just type + +\begin{verbatim} +createpkg latex2html +\end{verbatim} + +The resulting package should be available at /tmp or at the folder specified by the environment variable \$REPOS. To create and install the package, type + +\begin{verbatim} +createpkg --install latex2html +\end{verbatim} + +If the package has dependencies listed in a slack-required file that aren't installed in the system, then createpkg will try to process then before the desired package's SlackBuild: if the dependencies aren't available in the SlackBuild tree, then createpkg will call simplaret and try to install the package from a binary repository. If you want to avoid createpkg's dependency checking, just use it with the flag --no-deps. + +For more information about createpkg, type + +\begin{verbatim} +createpkg --help +\end{verbatim} + +or take a look at http://slack.sarava.org/trac/wiki/SlackBuilds. + +\section{Auxiliar applications} + +Simplepkg comes also with the following tools: + +\begin{itemize} + \item lspkg: show installed packages and its contents + \item rebuildpkg: rebuild a package based on its /var/log/packages entry + \item repos: creates and manages binary repositories + \item mkbuild: app to build slackware build scripts +\end{itemize} + +The command lspkg is used to show installed packages. Also, Simplepkg comes with an additional helper tool that recover installed packages which the original .tgz file was lost. The command rebuildpkg rebuilds a package from their entry in /var/log/packages. As an example, + +\begin{verbatim} +rebuildpkg coreutils +\end{verbatim} + +rebuilds the coreutils package using the files, scripts and metainformations stored in /var/log/packages/ and /var/log/scripts/. + +For their time, scripts repos and mkbuild are used, respectivelly, to create and manage binary repositories and to create SlackBuild scripts. + +\section{Configuration parameters} + +Simplepkg's config file is /etc/simplepkg/simplepkg.conf and it keeps parameters used by all scripts. If you want to change some of its parameters, do not edit this file. Use /etc/simplepkg/simplepkg.conf instead as it overrides the default settings. + +In this section, we won't cover any parameter that's just used by simplaret, whose settings are covered in its own documentation. + +\begin{itemize} + \item JAIL\_ROOT: Where jails are placed by mkjail. Default: "/vservers". + \item ADD\_TO\_JAIL\_LIST: Wheter mkjial should add new jails to /etc/simplepkg/jailist. Default is "1" (enabled). + \item TEMPLATES\_UNDER\_SVN: Set to yes if your templates will be placed in a subversion repository. Default is "no" (disabled). + \item TEMPLATE\_FOLDER: Where your templates will be located. Default is "/etc/simplepkg/templates" and dont change it except you know what you're doing. + \item TEMPLATE\_STORAGE\_STYLE: This variable controls in which folder / subfolder your templates will be stored. Default value is "own-folder" and you'll just need to change that if you're storing your templates using an old simplepkg format and wants to keep compatibilty. +\end{itemize} + +Its important to note that all boolean parameters in the config file can be set either to "1" or "yes" to enable and "0" or "no" to disable. + +\section{Additional information} + +Simplepkg was written by Silvio Rhatto (rhatto at riseup.net) and is released under GPL license. The code can be obtained from the subversion repository: + +\begin{verbatim} +svn checkout http://slack.sarava.org/simplepkg +\end{verbatim} + +Simplepkg's wiki is http://slack.sarava.org/trac/wiki/Simplepkg and its mailing list address is http://listas.sarava.org/wws/info/slack. + +\end{document} diff --git a/doc/simplepkg-pt_BR.tex b/doc/simplepkg-pt_BR.tex new file mode 100644 index 0000000..a80f0e7 --- /dev/null +++ b/doc/simplepkg-pt_BR.tex @@ -0,0 +1,397 @@ +\documentclass{article} +\usepackage[brazilian]{babel} +\usepackage[latin1]{inputenc} +\usepackage[dvips]{graphics} +\usepackage{hyperref} +\usepackage{html,makeid} + +\title{Gerenciamento de instalações e metapacotes com o simplepkg} +\author{Silvio Rhatto} + +\begin{document}\label{start} +\maketitle + +\begin{abstract} +O \emph{simplepkg} é um sistema de gerenciamento de sistemas slackware que roda sobre o pkgtool. Ele é composto por vários scripts que desempenham funções de administração e desenvolvimento de sistemas do tipo Slackware, procurando fechar um circuito de produção, envolvendo a construção, a instalação de pacotes e até mesmo a instalação do sistema de forma automatizada. + +Do lado do desenvolvedor/a, ele ajuda na criação de SlackBuilds e construção de pacotes. Do lado do administrador/a, ele possibilita a instalação automatizada de sistemas, instalação de pacotes e a criação de "templates" de instalação -- que contém todos os arquivos de configuração, informações de permissões e scripts de pós-instalação de uma dada máquina ou jaula. +\end{abstract} + +\section{Descrição} + +Todas as distribuições de GNU/Linux já tem algum sistema de empacotamento amadurecido. A questão agora é a praticidade de instalar e controlar o que está instalado, tanto pacotes como arquivos de configuração de uma máquina, além da facilidade na criação de pacotes. + +Imagine por exemplo se você precisa manter uma lista de pacotes de 200 máquinas slackware, sendo que algumas são usadas como desktop, outras como servidores web, alguma sendo o servidor de email e assim por diante. Imagine agora que você perca o disco de algumas dessas máquinas ou que precise cotidianamente reinstalar ou atualizar um sistema. + +Usar o cd de instalação do slackware e configurar na mão toda a vez que der um pau faria com que você ficasse louco/a e desperdiçasse muito tempo, além do que sempre ocorre de esquecermos algum detalhe ou pacote durante a configuração do sistema. Manter um backup completo de cada máquina, por outro lado, pode ser muito custoso se o número delas for muito grande. + +O \emph{simplepkg} permite que você mantenha um template para cada grupo de máquinas e com apenas um comando instalar o template numa partição. Além do template, você precisa configurar o \emph{simplepkg} para obter pacotes de um repositório local ou remoto. + +Gerenciar instalações e pacotes não é tudo o que o \emph{simplepkg} faz. Ele pode ser usado até na criação de jaula e vservers, podendo manter toda a configuração das máquinas num repositório Subversion. + +O \emph{simplepkg} funciona não apenas com o Slackware mas com qualquer port (oficial ou não) que siga minimamente os padrões oficiais. + +\section{Arquitetura} + +O \emph{simplepkg} é um conjunto de scripts escritos com a filosofia KISS (Keep It Simple, Stupid) em mente. Ele é um sistema muito simples, composto pelos seguintes comandos: + +\begin{itemize} + \item mkjail: constrói uma jaula/instalação de slackware numa pasta + \item templatepkg: criar ou adiciona pacotes a um template + \item lspkg: lista pacotes instalados + \item jail-update: inverso do jail-commit + \item jail-commit: atualiza o template + \item rebuildpkg: reconstrói um pacote a partir de sua entrada no /var/log/packages + \item simplaret: obtém pacotes de repositórios locais ou remotos + \item createpkg: baixa, compila e empacota software de acordo com scripts presentes num repositório + \item repos: cria e mantém repositórios + \item mkbuild: cria scripts de construção de pacotes +\end{itemize} + +\section{Instalando o simplepkg} + +Para baixar o pacote do \emph{simplepkg}, vá em \htmladdnormallink{http://slack.sarava.org/packages/noarch/}{http://slack.sarava.org/packages/noarch/}. Depois, basta usar o comando + +\begin{verbatim} +installpkg simplepkg-VERSAO-noarch-BUILD.tgz +\end{verbatim} + +\section{Usando o simplepkg} + +As três principais aplicações desse conjunto são: + +\begin{itemize} + \item Gerenciamento de pacotes + \item Criação e manutenção de jaulas + \item Criação de pacotes +\end{itemize} + +O gerencamento de pacotes é feito através do \htmladdnormallink{simplaret}{http://slack.sarava.org/simplaret}, e por ser algo bem específico está detalhado no artigo correspondente. As seções a seguir mostrarão como o \emph{simplepkg} pode ser utilizado para criar e manter jaulas, assim como também criar pacotes. + +\section{Criando templates de instalação} + +Originalmente, o \emph{simplepkg} foi desenvolvido para ajudar na automatização de instalações de sistemas slackware. Para isso, ele trabalha com templates -- listas com pacotes instalados, scripts e arquivos de configuração -- permitindo criar perfis de instalação que podem ser então usados para instalar o sistema numa outra partição ou criar um chroot. + +A construção de um template é feita através do programa templatepkg. Para criar um template de nome "meu-slackware" contendo a lista de pacotes atualmente instalados no seu sistema, digite + +\begin{verbatim} +templatepkg -c meu-slackware +\end{verbatim} + +A opção -c (ou --create) criará a pasta /etc/simplepkg/templates/meu-slackware, que conterá os seguintes componentes: + +\begin{itemize} + \item \emph{/etc/simplepkg/templates/meu-slackware/meu-slackware.d}: cópia de arquivos de configuração + \item \emph{/etc/simplepkg/templates/meu-slackware/meu-slackware.s}: scripts de pós-instalação + \item \emph{/etc/simplepkg/templates/meu-slackware/meu-slackware.perms}: informações sobre arquivos + \item \emph{/etc/simplepkg/templates/meu-slackware/meu-slackware.template}: lista de pacotes +\end{itemize} + +Esses quatro componentes são suficientes para armazenar todas as características de uma instalação de slackware: a lista de pacotes controla o software instalado (a partir do conteúdo da pasta \emph{/var/log/packages}), a cópia dos arquivos de configuração controla as personalizações feitas para o uso dos aplicativos e os scripts de pós-instalação cuidam de qualquer rotina que precisa ser realizada exatamente após a instalação do sistema. Já o arquivo de informações sobre arquivos contém as permissões, o dono/a e grupo de cada arquivo de configuração presente no template. + +Se você quiser criar um template a partir de uma instalação de slackware presente numa outra partição do sistema que não seja a raíz, basta usar um comando do tipo + +\begin{verbatim} +templatepkg -c meu-slackware /mnt/slackware +\end{verbatim} + +onde /mnt/slackware é o local onde o sistema alternativo está instalado. Após criado, o template possuirá apenas a lista de pacotes contendo o nome dos aplicativos instalados no seu sistema. Como a pasta /var/log/packages não preserva a ordem de instalação dos pacotes, então talvez você queira editar manualmente a lista de pacotes de um template. Para isso, use o comando + +\begin{verbatim} +templatepkg -e meu-slackware +\end{verbatim} + +Para adicionar um arquivo de configuração no seu novo template, basta dar um comando como + +\begin{verbatim} +templatepkg -a meu-slackware /etc/hosts +\end{verbatim} + +Isso adicionará o arquivo /etc/hosts no template "meu-slackware". Além de salvar o arquivo e copiá-lo automaticamente quando você instalar seu sistema, o \emph{simplepkg} ainda pode tomar conta de qualquer alteração que o /etc/hosts sofrer no sistema, seja mudança no conteúdo do arquivo, dono ou permissão. Se você ainda estiver armazenando seus templates num repositório svn (o que veremos a seguir), o \emph{simplepkg} pode ainda manter um histórico completo das alterações do arquivo. + +ATENÇÂO: evite ao máximo deixar arquivos contendo senhas ou chaves privadas num template. O lugar mais adequado para deixar esse tipo de coisa é num backup seguro. + +\section{Criando jaulas e replicando instalações} + +Uma vez que um template foi criado com uma lista de pacotes e opcionalmente com arquivos de configuração e scripts de pós-instalação (que serão detalhados a seguir), você pode replicar sua instalação de slackware utilizando o comando + +\begin{verbatim} +mkjail jaula meu-slackware +\end{verbatim} + +Isso cria uma nova árvore do slackware em /vservers/jaula contendo todos os pacotes e arquivos de configuração do template "meu-slackware". A instalação dos pacotes será feita pelo aplicativo \htmladdnormallink{simplaret}{http://slack.sarava.org/simplaret}, que deve estar configurado corretamente e cuja configuração padrão deve funcionar para a maioria dos casos. + +Se você quiser instalar essa jaula em outro local que não seja a pasta /vservers (esse local padrão pode ser mudado pelo arquivo de configuração do \emph{simplepkg}), basta usar um comando do tipo + +\begin{verbatim} +ROOT=/mnt mkjail hda2 meu-slackware +\end{verbatim} + +O comando acima faz exatamente o que você está pensando: replica sua instalação slackware em /mnt/hda2, dispensando totalmente o programa de instalação do slackware! + +Caso nenhum template for especificado, o mkjail utiliza o template /etc/simplepkg/defaults. O \emph{simplepkg} já vem com alguns templates padrões, presentes em /etc/simplepkg/defaults/templates. + +\section{Scripts de pós-instalação} + +Opcionalmente, é possível manter scripts de pós-instalação num template. Tais script são executados exatamente +após a instalação de uma jaula e cópia de arquivos de configuração pelo mkjail. Para criar ou editar um script +de pós-instalação, use um comando como + +\begin{verbatim} +templatepkg -b meu-slackware nome-do-script.sh +\end{verbatim} + +Isso adicionará o script nome-do-script.sh no template "meu-slackware". O mkjail passa dois argumentos para cada script de pós-instalação: a pasta superior e o nome da jaula ("/mnt" e "hda2" no nosso exemplo anterior). Assim, um exemplo de script seria algo como + +\begin{verbatim} +#!/bin/bash +chroot $1/$2/ sbin/ldconfig +\end{verbatim} + +\section{Listando o conteúdo de um template} + +Para listar os templates disponíveis ou o conteúdo de um template, use comandos como + +\begin{verbatim} +templatepkg -l +templatepkg -l meu-slackware +\end{verbatim} + +\section{Removendo arquivos de um template} + +Analogamente à forma como se adicona arquivos num template, removê-los pode ser feito com o seguinte comando: + +\begin{verbatim} +templatepkg -d meu-slackware /etc/hosts +\end{verbatim} + +Isso remove o arquivo /etc/hosts do template "meu-slackware". + +\section{Apagando um template} + +Para apagar um template, basta utilizar um comando como + +\begin{verbatim} +templatepkg -r meu-slackware +\end{verbatim} + +\section{Atualizando um template} + +Agora que já abordamos as opções do templatepkg, é hora de visitarmos um outro aplicativo, desta vez utilizado para manter um template atualizado. O jail-commit é um script que copia as alterações dos arquivos (conteúdo, propriedade e permissões) de um template a partir do conteúdo de uma jaula ou instalação. + +Por exemplo, caso se queira copiar as alterações da jaula /mnt/hda2 no template "meu-slackware", basta usar o comando + +\begin{verbatim} +jail-commit /mnt/hda2 meu-slackware +\end{verbatim} + +Além da lista de pacotes do template "meu-slackware" ser atualizada de acordo com a lista de pacotes presente em /mnt/hda2/var/log/packages, todos os arquivos de configuração presentes no template "meu-slackware" serão comparados com os correspondentes da pasta /mnt/hda2 e as diferenças são copiadas para o template. Da mesma forma, as permissões e informação de dono/grupo dos arquivos também é atualizada no template. + +O comando jail-commit possibilita que um template sempre esteja atualizado e refletindo a configuração atual de uma instalação de slackware. Se você quiser atualizar apenas a lista de pacotes de um template, porém, use + +\begin{verbatim} +templatepkg -u meu-template +\end{verbatim} + +Para facilitar ainda mais o controle das alterações do sistema, existe ainda uma facilidade do arquivo /etc/simplepkg/jailist. Esse arquivo serve, além de outros propósitos descritos na \htmladdnormallink{documentação do simplaret}{http://slack.sarava.org/simplaret}, para que o jail-commit saiba de antemão quais são as instalações de sistema do tipo Slackware presentes numa máquina, além da instalação principal na raíz do sistema. + +Suponha que uma máquina possua duas instalações de slackware, além da principal (raíz): + +\begin{itemize} + \item /mnt/slackware-1 usando o template "slackware-1" + \item /mnt/slackware-2 usando o template "slackware-2" +\end{itemize} + +Se o arquivo /etc/simplepkg/jailist contiver as seguintes linhas, + +\begin{verbatim} +/mnt/slackware-1 +/mnt/slackware-2 +\end{verbatim} + +então o comando + +\begin{verbatim} +jail-commit +\end{verbatim} + +atualizará o template "slackware-1" de acordo com o conteúdo da jaula /mnt/slackware-1 e o template "slackware-2" com o conteúdo da jaula /mnt/slackware-2. Se, além desses dois templates, existir um outro de nome "main", então o jail-commit sem argumentos também copiará as atualizações da instalação raíz, deixando-as no template "main". + +Você pode inclusive colocar uma entrada no crontab do tipo + +\begin{verbatim} +20 4 * * * jail-commit +\end{verbatim} + +para que seus templates sejam atualizados diariamente. Se você ainda possui o envio de emails configurado na sua máquina, então a saída do jail-commit será enviada pelo cron diariamente para seu email, contendo diffs das alterações de arquivos de configuração a lista de pacotes adicionados ou removidos no sistema. + +\section{Restaurando arquivos de configuração numa jaula} + +A operação contrária ao que o jail-commit faz também é possível: suponha que você mexeu na configuração do sistema mas se arrependeu das alterações e deseja voltar a configuração para o modo como ela se encontra no seu template, basta usar o comando + +\begin{verbatim} +jail-update /mnt/hda2 meu-slackware +\end{verbatim} + +\section{Armazenando as configurações no repositório Subversion} + +Para aumentar ainda mais a flexibilidade e o controle do conteúdo dos templates, é possível armazená-los num repositório Subversion. Para isso, edite o arquivo /etc/simplepkg/simplepkg.conf e deixe o parâmetro de configuração \emph{TEMPLATES\_UNDER\_SVN} com o valor "yes". + +Depois, crie um repositório subversion para armazenar seus templates, usando algo como + +\begin{verbatim} +svnadmin create /var/svn/simplepkg --fs-type fsfs +\end{verbatim} + +Com o repositório criado, basta importar seus templates com o comando + +\begin{verbatim} +templatepkg -e file:///var/svn/simplepkg +\end{verbatim} + +A partir daí, o comando jail-commit enviará automaticamente todas as alterações dos templates para o repositório subversion. Se, por outro lado, você quiser baixar as alterações dos templates que estão no repositório remoto para sua cópia local, use o comando + +\begin{verbatim} +templatepkg -s +\end{verbatim} + +Caso você queira importar uma pasta de templates de um repositório já existente, use + +\begin{verbatim} +templatepkg -i file:///var/svn/simplepkg +\end{verbatim} + +onde file:///var/svn/simplepkg é o camninho do repositório. + +\section{Atualização de jaulas} + +A atualização de jaulas e sistemas instalados é feita através do \htmladdnormallink{simplaret}{http://slack.sarava.org/simplaret} e também utiliza o arquivo /etc/simplepkg/jailist. Para mais informações a respeito, consulte a \htmladdnormallink{documentação do simplaret}{http://slack.sarava.org/simplaret} para mais detalhes. + +\section{Arquiteturas e versões diferentes} + +O \emph{simplepkg} foi idealizado para permitir que um mesmo template possa ser usado para criar jaulas de arquiteturas e versões diferentes de sistemas padrão slackware. A atualização desses sistemas também é unificada. Essa possibilidade só é permitida se você usa o \htmladdnormallink{simplaret}{http://slack.sarava.org/simplaret} e não o swaret como ferramenta de obtenção de pacotes. + +Por exemplo, para criar uma instalação de slackware 10.1 (assumindo que suas definições de repositórios do /etc/simplepkg/repos.conf contenham locais com slack 10.1), basta usar o comando + +\begin{verbatim} +VERSION=10.1 mkjail minha-jaula template-servidor +\end{verbatim} + +Arquiteturas diferentes também podem ser usadas. Se você está num sistema x86\_64 e quer instalar um slack 10.2 numa partição, experimente + +\begin{verbatim} +ARCH=i386 VERSION=10.2 ROOT=/mnt mkjail hda2 meu-slackware +\end{verbatim} + +Note que os templates independem de arquitetura e versão, já que eles só contém nomes de pacotes, arquivos de configuração e scripts. + +\section{Criando um pacote de um template} + +Se, por algum motivo, você quiser construir um pacote com o conteúdo de um template, experimente o comando + +\begin{verbatim} +templatepkg -p nome-do-template +\end{verbatim} + +No entanto, o \emph{simplepkg} foi criado para que esse tipo de comportamento seja evitado, já que é mais simples manter templates de configuração do que pacotes contendo a configuração de uma instalação. + +\section{Construindo pacotes} + +Até aqui, apenas mostramos os aplicativos do \emph{simplepkg} usados para a manutenção de instalações de slackware. No entanto, uma das outras finalidades desta suíte é a construção de pacotes, o que é feita pelo programa createpkg, Como dito anteriormente, o createpkg: baixa, compila e empacota software de acordo com scripts presentes num repositório de scripts, funcionando com um gerenciador de "ports" para slackware. + +O createpkg pode funcionar com qualquer tipo de script de construção de pacotes (SlackBuilds) mas funcionará melhor se os mesmos seguirem o padrão descrito na página + +\begin{verbatim} +http://slack.sarava.org/trac/wiki/SlackBuilds +\end{verbatim} + +Especificamente, o createpkg foi desenvolvido para utilizar os slackbuild disponíveis em \htmladdnormallink{http://slack.sarava.org/slackbuilds}{http://slack.sarava.org/slackbuilds}. O createpkg trabalha com repositórios do tipo subversion. + +Para obter os scripts do repositório do slack.sarava.org, digite + +\begin{verbatim} +createpkg --sync +\end{verbatim} + +Em seguida, você pode listas todos os scripts disponíveis: + +\begin{verbatim} +createpkg --list +\end{verbatim} + +Para buscar por um pacote, use + +\begin{verbatim} +createpkg --search latex2html +\end{verbatim} + +No caso, a busca é feita pelo SlackBuild do aplicativo "latex2html". Suponha agora que você queira construir o pacote desse aplicativo: + +\begin{verbatim} +createpkg latex2html +\end{verbatim} + +O pacote resultante estará na pasta /tmp ou no valor especificado pela variável de ambiente \emph{\$REPOS}. Para criar e também instalar o pacote, basta + +\begin{verbatim} +createpkg --install latex2html +\end{verbatim} + +Se o pacote possuir dependências listadas num arquivo slack-required e que não estiverem instaladas no sistema, o createpkg tentará processá-las uma a uma antes de tentar construir o pacote desejado: se as dependências não forem encontradas no repositório de scripts, então o createpkg tentará baixá-las de um repositório binário através do \htmladdnormallink{simplaret}{http://slack.sarava.org/simplaret}. Se você não quiser que a resolução de dependências seja seguida, use a opção --no-deps. + +Para mais detalhes de funcionamento, experimente o comando + +\begin{verbatim} +createpkg --help +\end{verbatim} + +ou então acesse a página http://slack.sarava.org/trac/wiki/SlackBuilds + +\section{Aplicativos auxiliares} + +O \emph{simplepkg} acompanha ainda alguns aplicativos auxiliares: + +\begin{itemize} + \item lspkg: lista pacotes instalados + \item rebuildpkg: reconstrói um pacote a partir de sua entrada no /var/log/packages + \item repos: cria e mantém repositórios + \item mkbuild: cria scripts de construção de pacotes +\end{itemize} + +O comando lspkg é um utilitário simples para a visualização de pacotes instalados no sistema. Já o rebuildpkg ajuda a recuperar pacotes instalados cujo tgz original foi perdido. O comando rebuildpkg reconstrói um pacote a partir de uma entrada no /var/log/packages. O comando + +\begin{verbatim} +rebuildpkg coreutils +\end{verbatim} + +reconstrói um pacote do coreutils usando os arquivos e as metainformações listadas no arquivo do /var/log/packages/ correspondente ao coreutils. + +Por fim, os scripts repos e mkbuild são os que se encontram na etapa de maior desenvolvimento: repos cria um repositório de pacotes a partir de uma pasta contendo pacotes do tipo pkgtool e o mkbuild é um aplicativo para auxiliar a criação de scripts de construção de pacotes que podem ser utilizados sozinhos ou pelo o createpkg. + +\section{Parâmetros de configuração} + +O arquivo de configuração do \emph{simplepkg} é o /etc/simplepkg/simplepkg.conf. Ele contém parâmetros de configuração de todos os scripts, porém neste texto não trataremos das opções específicas ao \htmladdnormallink{simplaret}{http://slack.sarava.org/simplaret}, as quais tem uma seção específica no artigo correspondente. + +Se você quiser alterar algum parâmetro, não edite esse arquivo: use, ao invés dele, o arquivo /etc/simplepkg/simplepkg.conf, pois este sobrescreve qualquer opção padrão. + +\begin{itemize} + \item \emph{JAIL\_ROOT}: pasta padrão onde as jaulas são criadas pelo mkjail. Valor padrão: "/vservers". + \item \emph{ADD\_TO\_JAIL\_LIST}: controla se uma jaula criada pelo mkjail deve ser adicionada automaticamente no arquivo /etc/simplepkg/jailist. O valor padrão é "1" (habilitado). + \item \emph{TEMPLATES\_UNDER\_SVN}: indica se os templates estão armazenados num repositório subversion. O valor padrão é "no" (não). + \item \emph{TEMPLATE\_FOLDER}: indica qual é a pasta de templates. O valor padrão é "/etc/simplepkg/templates" e não é recomendável alterá-lo. + \item \emph{TEMPLATE\_STORAGE\_STYLE}: controla a forma de armazenamento de templates. O valor padrão é "own-folder" e essa opção apenas deve ser modificada se você armazena seus templates num formato antigo do \emph{simplepkg} e deseja manter compatibilidade. +\end{itemize} + +Vale lembrar que todas as opções booleanas (isto é, que podem ser apenas habilitadas ou desabilitadas) do simplepkg.conf tem os seguintes valores permitidos: "1" e "yes" para habilitado e "0" ou "no" para desabilitado. + +\section{Mais informações} + +O \emph{simplepkg} foi escrito por Silvio Rhatto (rhatto at riseup.net) sob licença GPL e seu código fonte é disponibilizado através do repositório subversion: + +\begin{verbatim} +svn checkout http://slack.sarava.org/simplepkg +\end{verbatim} + +O wiki de desenvolvimento está em http://slack.sarava.org/trac/wiki/Simplepkg e o endereço da lista de discussão utilizada para discussões sobre o \emph{simplepkg} ou mesmo distribuições e pacotes do tipo Slackware é http://listas.sarava.org/wws/info/slack. + +\end{document} |