# ***** BEGIN LICENSE BLOCK *****
# Version: MPL 1.1/GPL 2.0/LGPL 2.1
#
# The contents of this file are subject to the Mozilla Public License Version
# 1.1 (the "License"); you may not use this file except in compliance with
# the License. You may obtain a copy of the License at
# http://www.mozilla.org/MPL/
#
# Software distributed under the License is distributed on an "AS IS" basis,
# WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
# for the specific language governing rights and limitations under the
# License.
#
# The Original Code is Aspicere2.
#
# The Initial Developer of the Original Code is
# the Ghislain Hoffman Software Engineering Lab, INTEC, University Ghent.
# Portions created by the Initial Developer are Copyright (C) 2006
# the Initial Developer. All Rights Reserved.
#
# Contributor(s):
#   Bram Adams <bram_DOT_adams_AT_ugent_DOT_be>
#
# Alternatively, the contents of this file may be used under the terms of
# either the GNU General Public License Version 2 or later (the "GPL"), or
# the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
# in which case the provisions of the GPL or the LGPL are applicable instead
# of those above. If you wish to allow use of your version of this file only
# under the terms of either the GPL or the LGPL, and not to allow others to
# use your version of this file under the terms of the MPL, indicate your
# decision by deleting the provisions above and replace them with the notice
# and other provisions required by the GPL or the LGPL. If you do not delete
# the provisions above, a recipient may use your version of this file under
# the terms of any one of the MPL, the GPL or the LGPL.
#
# ***** END LICENSE BLOCK *****

[Some parts of the code are distributed under the Illinois Open Source License, see autoconf/LICENSE.TXT.]

For install and upgrade instructions, look at INSTALL and UPGRADE respectively.

To get started, look at the various examples in $ASPICERE2_SRC/test/Feature. You'll see that you can invoke Aspicere2 like this:

aspicere2.sh sourcefile1.c ... sourcefileN.c -o a.out -aspects aspects.lst -modules modules.lst

where aspects.lst is a file with relative/absolute paths to all relevant aspects (possibly none) and modules.lst the same for Prolog files containing user-defined rules and/or facts.

Best places to start learning Aspicere2:
 + http://www.aosd.net/workshops/splat/2007/papers/adams.pdf (explains key language features, but without cflow or sequences)
 + $ASPICERE2_SRC/test/Feature/SPLAT07 (annotations, local continuation join points, join point properties and generic advice)
 + $ASPICERE2_SRC/test/Feature/CFlowAroundCallCall (cflow)
 + $ASPICERE2_SRC/test/Feature/MostRecent (temporal pointcuts)
 + $ASPICERE2_SRC/test/Feature/CSOMFeatures (idem)
 + $ASPICERE2_SRC/docs/internals/arch.pdf, i.e. beginning of documentation of Aspicere2's internals (issue "make" inside the directory first; you need pdflatex to be installed)

- WARNINGS:
    * the aspect parser is not very forgiving, so always put advice signatures (ending in a colon) on one line, followed by the pointcut on the next lines of which the last one ends with an opening brace or semi-colon (for introductions);
    * for the same reasons: do not put C comment tokens around advice, although you can comment out parts of the advice BODY.
    * likewise, pay attention to the syntax in $ASPICERE2_SRC/test/Feature/MostRecent/*.ac (all pcd subexpressions in onne sequence time step should be on the same line)
    * use "invocation" instead of the "call"-pointcut for name clashing issues in SWI Prolog

- Pointcuts:
    * are transformed into Prolog rules ("&&" becomes ",", "||" becomes ";" and "!!" becomes "\+")
    * look at $ASPICERE2_SRC/lib/weaver/predicates.pl and $ASPICERE2_SRC/lib/native/NativePredicates.cpp for possible predefined rules (the tests in $ASPICERE2_SRC/test/Feature give meaningful examples of their use)
    * you can add your own rules and facts in .pl-files listed in the modules.lst you provide to aspicere2.sh

- Brief overview of architecture (more to come in $ASPICERE2_INSTALL/docs):
    * the reify pass ($ASPICERE2_SRC/lib/weaver/Reifier.cpp) reifies all interesting program characteristics like method definitions, calls, arguments, ... as Prolog facts
    * the match pass ($ASPICERE2_SRC/lib/weaver/Matcher.cpp) queries the pointcuts on top of the Prolog fact base to find join point matches and sorts the resulting set of join points ($ASPICERE2_SRC/lib/weaver/JoinPointShadowSorter.cpp)
    * the weave phase ($ASPICERE2_SRC/lib/weaver/Weaver.cpp) weaves the right advice at the matched join points:
       + first, execution join point shadows are extracted and converted into call shadows
       + process join point shadow context used by more than one advice instance at the same shadow
       + weave in dedicated "mungers" per shadow type (call and execution shadows in $ASPICERE2_SRC/lib/weaver/CallMunger.cpp, ...)

- Running and debugging test cases:
    * "make check" from within $ASPICERE2_BUILD performs all tests
    * running "make check TESTSUITE=Feature/NameOfSubDirOfFeature" from $ASPICERE2_BUILD limits tests to only one subdirectory
    * notice that each test subdirectory contains 2 files whose names match "*RUN" (one only doing weaving, another one doing extra optimisation afterwards),
    * to run a test in a debugger like gdb or ddd, do "./manual.sh name_of_debugger" from inside the relevant test subdirectory