Installing and running the Acme Map Generator (AMG) is straightforward. Create a subdirectory dedicated to AMG, and un-gzip and un-tar the distribution there. Under Unix/Linux, the command % tar zxvf amg.tgz will do this one one step. You can then start the command-line version of AMG by starting SICStus Prolog and loading the file amg.pl (e.g., with the shell command % sicstus -l amg.pl or, if the SICStus Emacs interface is installed, by opening amg.pl in Emacs and typing C-c C-c f.) Make sure you compile, not consult, the source code! Start the AMG by entering "amg." (i.e., by typing "amg.") at the Prolog prompt, `| ?-'. Unless something goes wrong, you should never see the Prolog prompt again after starting the AMG. If you do, you can try restarting the AMG, or entering "C-c e" -- "C-c C-c e" under Emacs -- to exit Prolog and starting all over from scratch. Anytime things get too weird, "C-c e" (or "C-c C-c e") should get you out of Prolog. Don't worry about losing state; persistent storage gets updated incrementally as you run the system. The following transcript shows how the command-line interface works. [rar@coyote amg-distribution]$ sicstus -l amg.pl {compiling /export/u1/homes/rar/pegasys/acme/amg-distribution/amg.pl...} | ?- amg. ************************************************************** *********** *********** ********** WELCOME TO THE ACME MAP GENERATOR! ********** *********** *********** ************************************************************** Do you want to 1. Start from where you left off, or 2. Start fresh? Enter 1 or 2 (followed by a '.'): 2. Do you want to 1. Transform an architecture, 2. Compose mappings between architectures, or 3. Quit? Enter 1, 2, or 3 (followed by a '.'): 1. There are 1 architectural descriptions available for transformation: 1. concrete_description Since only one is available, it has been automatically selected. There are 2 transformations available: 1. Bundle connectors 2. Replace connector-component-connector chain by a connector Select one by entering a number between 1 and 2 (followed by a "."): 1. Enter name of generated architecture (followed by a '.'): intermediate_1. 4 matches found: 1. [@s/sys,@c1/comp1,@op1/op12,@op2/op13,@c2/buf,@ip1/bip1,@ip2/bip2,@k1/k11,@or1/or11,@ir1/ir11,@k2/k12,@or2/or12,@ir2/ir12] 2. [@s/sys,@c1/comp1,@op1/op13,@op2/op12,@c2/buf,@ip1/bip2,@ip2/bip1,@k1/k12,@or1/or12,@ir1/ir12,@k2/k11,@or2/or11,@ir2/ir11] 3. [@s/sys,@c1/buf,@op1/bip1,@op2/bip2,@c2/comp1,@ip1/op12,@ip2/op13,@k1/k11,@or1/ir11,@ir1/or11,@k2/k12,@or2/ir12,@ir2/or12] 4. [@s/sys,@c1/buf,@op1/bip2,@op2/bip1,@c2/comp1,@ip1/op13,@ip2/op12,@k1/k12,@or1/ir12,@ir1/or12,@k2/k11,@or2/ir11,@ir2/or11] Select one by entering a number between 1 and 4 (followed by a "."): 3. Generated the description system sys = { component buf = {ports {bip1; bop}}; component comp1 = {ports {op12; op11; ip11; ip12}}; connector k11 = {roles {ir11; or11}}; attachments { k11.or11 to buf.bip1; k11.ir11 to comp1.op12; k2.ir2 to buf.bop; k2.or2 to comp2.ip22; k3.ir3 to comp1.op11; k3.or3 to comp2.ip21 }; component comp2 = {ports {op21; op22; ip21; ip22}}; connector k2 = {roles {ir2; or2}}; connector k3 = {roles {ir3; or3}} } linked to description concrete_description by the mapping map concrete_description_to_intermediate_1 with { < bip1, bip2 > to bip1; < op12, op13 > to op12; < k11, k12 > to k11; < ir11, bip2 > to ir11; < or11, or12 > to or11 } Do you want to 1. Transform an architecture, 2. Compose mappings between architectures, or 3. Quit? Enter 1, 2, or 3 (followed by a '.'): 1. There are 2 architectural descriptions available for transformation: 1. concrete_description 2. intermediate_1 Select one by entering a number between 1 and 2 (followed by a "."): 2. There are 2 transformations available: 1. Bundle connectors 2. Replace connector-component-connector chain by a connector Select one by entering a number between 1 and 2 (followed by a "."): 2. Enter name of generated architecture (followed by a '.'): intermediate_2. 2 matches found: 1. [@s/sys,@c1/comp1,@op/op12,@buf/buf,@bip/bip1,@bop/bop,@c2/comp2,@ip/ip22,@k1/k11,@ir1/ir11,@or1/or11,@k2/k2,@ir2/ir2,@or2/or2] 2. [@s/sys,@c1/comp2,@op/ip22,@buf/buf,@bip/bop,@bop/bip1,@c2/comp1,@ip/op12,@k1/k2,@ir1/or2,@or1/ir2,@k2/k11,@ir2/or11,@or2/ir11] Select one by entering a number between 1 and 2 (followed by a "."): 1. Generated the description system sys = { component comp1 = {ports {op12; op11; ip11; ip12}}; component comp2 = {ports {ip22; op21; op22; ip21}}; connector buf = {roles {ir11; or2}}; attachments { buf.ir11 to comp1.op12; buf.or2 to comp2.ip22; k3.ir3 to comp1.op11; k3.or3 to comp2.ip21 }; connector k3 = {roles {ir3; or3}} } linked to description intermediate_1 by the mapping map intermediate_1_to_intermediate_2 with { [ from_connector = k11; from_role = or11; from_port = bip1; through_component = buf; to_port = bop; to_role = ir2; to_connector = k2 ] to buf } Do you want to 1. Transform an architecture, 2. Compose mappings between architectures, or 3. Quit? Enter 1, 2, or 3 (followed by a '.'): 1. There are 3 architectural descriptions available for transformation: 1. concrete_description 2. intermediate_1 3. intermediate_2 Select one by entering a number between 1 and 3 (followed by a "."): 3. There are 2 transformations available: 1. Bundle connectors 2. Replace connector-component-connector chain by a connector Select one by entering a number between 1 and 2 (followed by a "."): 1. Enter name of generated architecture (followed by a '.'): abstract. 4 matches found: 1. [@s/sys,@c1/comp1,@op1/op12,@op2/op11,@c2/comp2,@ip1/ip22,@ip2/ip21,@k1/buf,@or1/or2,@ir1/ir11,@k2/k3,@or2/or3,@ir2/ir3] 2. [@s/sys,@c1/comp1,@op1/op11,@op2/op12,@c2/comp2,@ip1/ip21,@ip2/ip22,@k1/k3,@or1/or3,@ir1/ir3,@k2/buf,@or2/or2,@ir2/ir11] 3. [@s/sys,@c1/comp2,@op1/ip22,@op2/ip21,@c2/comp1,@ip1/op12,@ip2/op11,@k1/buf,@or1/ir11,@ir1/or2,@k2/k3,@or2/ir3,@ir2/or3] 4. [@s/sys,@c1/comp2,@op1/ip21,@op2/ip22,@c2/comp1,@ip1/op11,@ip2/op12,@k1/k3,@or1/ir3,@ir1/or3,@k2/buf,@or2/ir11,@ir2/or2] Select one by entering a number between 1 and 4 (followed by a "."): 1. Generated the description system sys = { component comp1 = {ports {op12; ip11; ip12}}; component comp2 = {ports {ip22; op21; op22}}; connector buf = {roles {or2; ir11}}; attachments { buf.ir11 to comp1.op12; buf.or2 to comp2.ip22 } } linked to description intermediate_2 by the mapping map intermediate_2_to_abstract with { < op12, op11 > to op12; < ip22, ip21 > to ip22; < buf, k3 > to buf; < or2, op11 > to or2; < ir11, ir3 > to ir11 } Do you want to 1. Transform an architecture, 2. Compose mappings between architectures, or 3. Quit? Enter 1, 2, or 3 (followed by a '.'): 2. There are 4 candidates for the beginning of the abstraction chain: 1. concrete_description 2. intermediate_1 3. intermediate_2 4. abstract Select one by entering a number between 1 and 4 (followed by a "."): 1. There are 4 candidates for the end of the abstraction chain: 1. concrete_description 2. intermediate_1 3. intermediate_2 4. abstract Select one by entering a number between 1 and 4 (followed by a "."): 4. Generated the map map concrete_description_to_abstract with { < < op12, op13 >, op11 > to op12; < ip22, ip21 > to ip22; < [ from_connector = < k11, k12 >; from_role = < or11, or12 >; from_port = < bip1, bip2 >; through_component = buf; to_port = bop; to_role = ir2; to_connector = k2 ], k3 > to buf; < or2, op11 > to or2; < < ir11, bip2 >, ir3 > to ir11 } Do you want to 1. Transform an architecture, 2. Compose mappings between architectures, or 3. Quit? Enter 1, 2, or 3 (followed by a '.'): 3. Okay, bye! A few comments on the above. The meaning of "Start fresh" is defined by the contents of the three INITIAL-*-LOG-FILE.pl files. If you want to start with a concrete architectural description other than concrete_description, change INITIAL-DESCRIPTION-LOG-FILE.pl -- which is a list of descriptions the AMG knows about after a fresh start -- either by replacing "concrete_description" by the name of your preferred starting point, or adding another clause to to the definition of 'DESCRIPTION'/1. To you add new abstraction rules, add new clauses to "TRANSFORM'/2 in INITIAL-TRANSFORMATION LOG-FILE.pl. (You shouldn't have to mess with INITIAL-TREE-LOG-FILE.pl, since the tree of abstractions should always be empty when you start fresh.) The other three *-LOG-FILE.pl files are used to record the development of the tree of abstractions. Currently, no new transformations are generated at runtime, so there's no real need for TRANSFORM-LOG-FILE.pl. Annoyingly, because there is only one file of descriptions and one file of links, you should start the development of each tree in its own subdirectory. If you decide you'd like to eradicate some branch of the abstraction tree, you can (carefully!) edit DESCRIPTION-LOG-FILE.pl and TREE-LOG-FILE.pl by hand to neliminate the undesired descriptions and links, and then restart the AMG "where you left off". A couple of obvious shortcomings illustated by the demo are that our Acme prettyprinter has no concept of line length, and our matcher has no concept of symmetry. For example, the "Bundle connectors" from-pattern will always match a description 4N times, for some natural number N, because the result of "reversing the direction" of either connector in a match produces another match. Similarly, "Replace connector-component-connector chain by a connector" will always match 2N times, for some N. A problem that doesn't show up in the written transscript is that searching for all matches can be slow: finding all matches of the "Bundle connectors" from-pattern to concrete_description takes around 5 seconds with my 300 MHz Pentium-II. Both the speed problem and the symmetry problem could be fixed by letting user specify desired metavariable matches prior to matching. But doing this in a command line-based interface seemed too awkward, so look for this feature when an improved version of the Tcl/Tk-based GUI becomes available. If you have problems, (1) let me (rar@csl.sri.com) know, and (2) "Use the Source!" -- not necessarily in that order. I will not attempt to describe use of the GUI in any detail here. Start it by executing amg.tcl. Basically, you select a starting point choosing "Select New Top Architecture" entry in the Select menu, you transform an architecture by left-clicking on it's name in the tree, and you compose mappings by choosing "Compose Mappings" entry in the Select menu. Remember that this is just a first approxiamtion to the GUI; don't expect too much, and you won't be disappointed. Note: The AMG has been made available under the terms of Version 2 of the GNU General Public License, a copy of which is included in the file LICENSE.txt