Date: Tue, 2 Apr 2002 14:06:19 -0300 From: Mario Sergio Fujikawa Ferreira <lioux@FreeBSD.org> To: freebsd-doc@FreeBSD.org Cc: Hammurabi Mendes <hmendes_br@yahoo.com>, Patrick Li <pat@databits.net>, freebsd-ports@FreeBSD.org Subject: Porter's Handbook info on MASTER_SITES:n Message-ID: <20020402170641.65924.qmail@exxodus.fedaykin.here>
next in thread | raw e-mail | index | archive | help
--VS++wcV0S1rZb1Fb Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Hi, I would like review on the following addition to Porter's Handbook. Of course, this still has to be sgml(ified) but I would like to get peer review first. Not only on both grammar and format properness but also in the wording... it is a bit too computer language related. It is a piece on the MASTER_SITES:n (also known as MASTER_SITES_NN) patch added http://www.freebsd.org/cgi/cvsweb.cgi/ports/Mk/bsd.port.mk revision 1.396 The documentation did not come together with the code.... cause I both find it hard to write documentation other than technical one (which is not exactly the focus of Porter's Handbook) and wanted to get the code last bugs (revision 1.407) before people would begin using it. All input is welcome. (useful mind you ;) Edited version of original message http://www.freebsd.org/cgi/mid.cgi?db=3Dirt&id=3D20011001030044.A1185@exxod= us.fedaykin.here Regards, --=20 Mario S F Ferreira - DF - Brazil - "I guess this is a signature." Computer Science Undergraduate | FreeBSD Committer | CS Developer flames to beloved devnull@someotherworldbeloworabove.org feature, n: a documented bug | bug, n: an undocumented feature ----- OpenBSD has a neat feature, inside the DISTFILES area, files can be postfixed with :n where n can be [0-9] and denotes a group. For example: DISTFILES=3D alfa:0 beta:1 Distfile alfa will be associated with variable MASTER_SITES0 instead of our common MASTER_SITES and beta with MASTER_SITES1 This is a very neat feature which can decrease that endless search for the correct download site. Just picture 2 DISTFILES and 20 MASTER_SITES, the sites are slow as hell and (of course); while beta is carried by all MASTER_SITES, alfa can only be found in MASTER_SITE number 20. Seems like a waste to check all of them if the maintainer knew beforehand, does not it? Not a good start for that lovely weekend. :-) Now that you got the picture, just imagine more distfiles and more MASTER_SITES. I am sure that our "distfiles survey meister" would appreciate the network strain relieve this would bring. :) ------ After debating this for some time and collecting suggestions, here goes our version of this idea: 1) Elements can be postfixed with :n where n is [^:,]+, i.e., n could conceptually be any alphanumerical string but we will limit it to [a-zA-Z_][0-9a-zA-Z_]+ for now. String matching is case sensitive, i.e., n word is different from N one. However, the following words cannot be used for postfixing purposes since they yield special meaning: default ALL, all (they are used internally in (C2***) below) Furthermore, DEFAULT is a special purpose word (check 3). 2) Elements postfixed with :n belong to the group n, :m belong to group m and so forth 3) Elements without a postfix are groupless; that is, they all do belong to the special group DEFAULT. If you postfix any elements with DEFAULT, you are just being reduntant unless you want to have an element belonging to both DEFAULT and other groups at the same time (check (5) below) The following examples are equivalent but the first one is preferred: MASTER_SITES=3D alfa MASTER_SITES=3D alfa:DEFAULT 4) Groups are not exclusive, an element can belong to several different groups at the same time and a group can have either several different elements or none. Repeated elements within the same group will be simply that, repeated elements 5) The comma ',' operator; This one is tempting, what if we want an element belonging to several groups at the same time? Instead of repeating it several times, each time with a different postfix, we could list several groups at once in a single postfix. For instance, :m,n,o meaning an element belongs to group m, n and o All following examples are equivalent but the last one is preferred: MASTER_SITES=3D alfa alfa:SOME_SITE MASTER_SITES=3D alfa:DEFAULT alfa:SOME_SITE MASTER_SITES=3D alfa:SOME_SITE,DEFAULT MASTER_SITES=3D alfa:DEFAULT,SOME_SITE 6) Group semantics can be used in any of the following variables {MASTER,PATCH}{FILES,_SITE_SUBDIR,_SITES} with the following syntax: 6.1) all {MASTER,PATCH}_{SITE_SUBDIR,SITES} elements must be terminated with the character slash '/'. If any elements belong to any groups, the group postfix :n will come right after the terminator '/'. The patch will rely on the existence of this terminator '/' to avoid confusing elements where a :n is a valid part of the element with occurences where :n denotes group n. For compatibility purposes, since the '/' terminator was not required before in {MASTER,PATCH}_SITE_SUBDIR elements, even if an element is postfixed with :n, if the postfix immediate preceeding character isn't a '/' then :n will be considered a valid part of the element instead of a group postfix MASTER_SITE_SUBDIR=3D old:n new/:NEW directories within group DEFAULT -> old:n directories within group NEW -> new MASTER_SITES=3D http://site1/%SUBDIR%/ http://site2/:DEFAULT \ http://site3/:group3 http://site4/:group4 \ http://site5/:group5 http://site6/:group6 \ http://site7/:DEFAULT,group6 \ http://site8/%SUBDIR%/:group6,group7 \ http://site9/:group8 DISTFILES=3D file1 file2:DEFAULT file3:group3 \ file4:group4,group5,group6 file5:grouping \ file6:group7 MASTER_SITE_SUBDIR=3D directory-trial:1 directory-n/:groupn \ directory-one/:group6,DEFAULT \ directory - results: o file1 will be fetched from ${_MASTER_SITE_OVERRIDE} http://site1/directory/ http://site1/directory-one/ http://site1/directory-trial:1/ http://site2/ http://site7/ ${_MASTER_SITE_BACKUP} o file2 will be fetched from same as file1 since they belong to the same group ${_MASTER_SITE_OVERRIDE} http://site1/directory/ http://site1/directory-one/ http://site1/directory-trial:1/ http://site2/ http://site7/ ${_MASTER_SITE_BACKUP} o file3 will be fetched from ${_MASTER_SITE_OVERRIDE} http://site3/ ${_MASTER_SITE_BACKUP} o file4 will be fetched from ${_MASTER_SITE_OVERRIDE} http://site4/ http://site5/ http://site6/ http://site7/ http://site8/directory-one/ ${_MASTER_SITE_BACKUP} o file5 will be fetched from ${_MASTER_SITE_OVERRIDE} ${_MASTER_SITE_BACKUP} o file6 will be fetched from ${_MASTER_SITE_OVERRIDE} http://site8/directory-one/ ${_MASTER_SITE_BACKUP} 7) How do I group one of the special variables from bsd.sites.mk? Example MASTER_SITES=3D http://site1/ ${MASTER_SITE_SOURCEFORGE:S/$/:sourceforge,= TEST/} DISTFILES=3D something.tar.gz:sourceforge - something.tar.gz will be fetched from all sites within ${MASTER_SITE_SOURCEFORGE} 8) How do I use this with PATCH* variables? All examples were done with MASTER* but they are the same for PATCH* PATCH_SITES=3D http://site1/ http://site2/:test PATCHFILES=3D patch1:test 9) All sites within a given group are sorted according to ${MASTER_SORT_AWK}. All groups within {MASTER,PATCH}SITES are sorted ------ What changes for my ports? What does not? C1) All current ports remain the same. The feature code is only activated if there are elements postfixed with :n given the aforementioned syntax rules, specially (6) C2) The port targets remain the same: checksum, makesum, patch, configure, build, ... All of them, with the obvious exceptions of do-fetch, fetch-list, master-sites and patch-sites - do-fetch: deploys the new grouping postfixed {DIST,PATCH}FILES with their matching group elements within {MASTER,PATCH}_SITES which use matching group elements within {MASTER,PATCH}_SITE_SUBDIR Check (6.1) for an example - fetch-list: works like old fetch-list with the exception that it groups just like do-fetch - {master,patch}-sites: (incompatible with older versions) only returns the elements of group DEFAULT, in fact, it executes targets {master,patch}-sites-default respectively * using target {master,patch}-sites is preferred to directly checking {MASTER,PATCH}_SITES. Also, directly checking is not guaranteed to work in any future versions ** (NEW) there are {master,patch}-sites-n targets which will list the elements of the respective group n within {MASTER,PATCH}_SITES. {master,patch}-sites-DEFAULT will return the elements of group DEFAULT *** (NEW) there are new targets {master,patch}-sites-all which do the work of the old {master,patch}-sites. Return the elements of all groups as if they all belonged to the same group with the caveat that it lists as many both MASTER_SITE_BACKUP and MASTER_SITE_OVERRIDE as there are groups defined within {DIST,PATCH}FILES --VS++wcV0S1rZb1Fb Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.6 (FreeBSD) Comment: For info see http://www.gnupg.org iD8DBQE8qeUgXvSymrg2XlURAtS/AJ4rvdf9UltU71Pt61ijcCz2P1xC+wCfVtOZ ATwH+C0qTK/Q5/S/ZA4uSm0= =zzEX -----END PGP SIGNATURE----- --VS++wcV0S1rZb1Fb-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20020402170641.65924.qmail>