[Update documentation on configurations Duncan Coutts **20071012015338 Describe the new syntax and make variuous changes to the description of the meaning. ] { hunk ./doc/Cabal.xml 3 - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ + [ hunk ./doc/Cabal.xml 140 -Library { +Library hunk ./doc/Cabal.xml 146 -} + hunk ./doc/Cabal.xml 164 -Executable program1 { +Executable program1 hunk ./doc/Cabal.xml 168 -} hunk ./doc/Cabal.xml 169 -Executable program2 { +Executable program2 hunk ./doc/Cabal.xml 174 -} + hunk ./doc/Cabal.xml 189 -Library { +Library hunk ./doc/Cabal.xml 192 -} hunk ./doc/Cabal.xml 193 -Executable program1 { +Executable program1 hunk ./doc/Cabal.xml 197 -} hunk ./doc/Cabal.xml 198 -Executable program2 { +Executable program2 hunk ./doc/Cabal.xml 202 -} + hunk ./doc/Cabal.xml 427 - Custom, some tools will be able to - build the package without using the setup script. + Custom, some tools such as + cabal-setup will be able to + build the package without using the setup script. So if you are + just using the default Setup.hs then set + the build type as Simple. hunk ./doc/Cabal.xml 454 - for this package. + for this package. It will be installed with the package. + hunk ./doc/Cabal.xml 468 + For example: + Copyright: (c) 2006-2007 Joe Bloggs + hunk ./doc/Cabal.xml 1041 -Cabal-Version: >= 1.1.7 +Cabal-Version: >= 1.2 hunk ./doc/Cabal.xml 1047 -Flag Debug { +Flag Debug hunk ./doc/Cabal.xml 1050 -} hunk ./doc/Cabal.xml 1051 -Flag WebFrontend { +Flag WebFrontend hunk ./doc/Cabal.xml 1053 - -- defaults to True -} + -- Cabal checks if the configuration is possible, first + -- with this flag set to True and if not it tries with False hunk ./doc/Cabal.xml 1056 -Library { +Library hunk ./doc/Cabal.xml 1061 - - if flag(debug) { + if flag(debug) hunk ./doc/Cabal.xml 1063 - if !os(win32) { + if !os(win32) hunk ./doc/Cabal.xml 1065 - } else { + else hunk ./doc/Cabal.xml 1067 - } - } hunk ./doc/Cabal.xml 1068 - if flag(webfrontend) { + if flag(webfrontend) hunk ./doc/Cabal.xml 1070 - Exposed-Modules: Testing.WebStuff - } -} + Other-Modules: Testing.WebStuff hunk ./doc/Cabal.xml 1072 -Executable test1 { +Executable test1 hunk ./doc/Cabal.xml 1077 - if flag(debug) { + if flag(debug) hunk ./doc/Cabal.xml 1080 - } -} + hunk ./doc/Cabal.xml 1083 + Layout + Flags, conditionals, library and executable sections use layout to + indicate structure. This is very similar to the Haskell layout rule. + Entries in a section have to all be indented to the same level which must + be more than the section header. Tabs are not allowed to be used for + indentation. + + As an alternative to using layout you can also use explicit braces + {}. In this case the indentation of entries in a + section does not matter, though different fields within a block must be + on different lines. Here is a bit of the above example again, using + braces: + + Using explicit braces rather than indentation for layout + + Name: Test1 +Version: 0.0.1 +Cabal-Version: >= 1.2 +License: BSD3 +Author: Jane Doe +Synopsis: Test package to test configurations +Category: Example + +Flag Debug { + Description: Enable debug support + Default: False +} + +Library { + Build-Depends: base + Exposed-Modules: Testing.Test1 + Extensions: CPP + if flag(debug) { + GHC-Options: -DDEBUG + if !os(win32) { + CC-Options: "-DDEBUG" + } else { + CC-Options: "-DNDEBUG" + } + } +} + + + + hunk ./doc/Cabal.xml 1168 - if condition { - property-descriptions-or-conditionals* - } - or - - if condition { - property-descriptions-or-conditionals* - } else { - property-descriptions-or-conditionals* - } + if condition + property-descriptions-or-conditionals* + or + + if condition + property-descriptions-or-conditionals* + else + property-descriptions-or-conditionals* hunk ./doc/Cabal.xml 1178 - Note that the condition and the opening brace have to - be all on the same line. Similar for the closing brace and - a possible else part. In particular, it - is not possible to have multiple - closing braces on one line or to have the - else followed directly by an - if. - Properties inside an if block must be indented at - least as much as the opening if - (preferably more). + Note that the if and the condition have to + be all on the same line. hunk ./doc/Cabal.xml 1205 - against the result of calling - System.Info.os on the target system. - If both are the same, this test evaluates to true, - otherwise false. + against System.Info.os on + the target system. There is unfortunately some disagreement + between Haskell implementations about the standard values of + System.Info.os. Cabal canonicalises it so + that in particular os(windows) works on all + implementations. If the canonicalised os names match, this test + evaluates to true, otherwise false. The match is + case-insensitive. hunk ./doc/Cabal.xml 1223 - name. The argument is tested - against the result of calling - System.Info.arch on the target system. - If both are the same, this test evaluates to true, - otherwise false. + name. The argument is matched + against System.Info.arch on the target system. + If the arch names match, this test evaluates to true, + otherwise false. The match is case-insensitive. hunk ./doc/Cabal.xml 1236 - Tests for the configured compiler. An optional + Tests for the configured Haskell implementation. An optional hunk ./doc/Cabal.xml 1239 - configured compiler is of the right type and matches the + configured implementation is of the right type and matches the hunk ./doc/Cabal.xml 1241 - otherwise false. + otherwise false. The match is case-insensitive. hunk ./doc/Cabal.xml 1262 - Always evaluates to true. + Constant value true. hunk ./doc/Cabal.xml 1270 - Always evaluates to false. + Constant value false. hunk ./doc/Cabal.xml 1276 + + Resolution of Conditions and Flags + If a package descriptions specifies configuration flags + the package user can control these in several ways (see + ). If the user does not fix the + value of a flag, Cabal will try to find a flag assignment in the + following way. + + + For each flag specified, it will assign its default + value, evaluate all conditions with this flag assignment, + and check if all dependencies can be satisfied. If this + check succeeded, the package will be configured with those + flag assignments. + + + If dependencies were missing, the last flag (as by + the order in which the flags were introduced in the + package description) is tried with its alternative value + and so on. This continues until either an assignment is + found where all dependencies can be satisfied, or all + possible flag assignments have been tried. + + + + To put it another way, Cabal does a complete backtracking + search to find a satisfiable packge configuration. It is only the + dependencies specified in the build-depends field + in conditional blocks that determine if a particular flag assignment + is satisfiable (build-tools are not considered). + The order of the declaration and the default value of the flags + determines the search order. Flags overriden on the command line fix + the assignment of that flag, so no backtracking will be tried for + that flag. + + If no suitable flag assignment could be found, the + configuration phase will fail and a list of missing + dependencies will be printed. Note that this resolution + process is exponential in the worst case (i.e., in the case + where dependencies cannot be satisfied). There are some + optimizations applied internally, but the overall complexity + remains unchanged. + hunk ./doc/Cabal.xml 1320 - Conditional Resolution + Meaning of field values when using conditionals hunk ./doc/Cabal.xml 1322 - chosen (see ), all - conditionals are evaluated, and the package description is - combined into a flat package descriptions. If property - descriptions occur both inside a conditional and outside - are combined, using the following rules. + chosen, all conditionals are evaluated, and the package description + is combined into a flat package descriptions. If the same field + both inside a conditional and outside then they are combined using + the following rules. hunk ./doc/Cabal.xml 1335 -if impl(ghc) || impl(hugs) { +if impl(ghc) || impl(hugs) hunk ./doc/Cabal.xml 1337 -} + hunk ./doc/Cabal.xml 1339 - Extensions: CPP MultiParamTypeClasses + Extensions: CPP, MultiParamTypeClasses hunk ./doc/Cabal.xml 1348 -if flag(useothermain) { +if flag(useothermain) hunk ./doc/Cabal.xml 1350 -} + hunk ./doc/Cabal.xml 1352 - if flag(useothermain) { + if flag(useothermain) hunk ./doc/Cabal.xml 1354 -} else { +else hunk ./doc/Cabal.xml 1356 -} + hunk ./doc/Cabal.xml 1535 - Cabal supports this with a trivial setup library &Make;, + Cabal supports this with the build-type + Make and a trivial setup library &Make;, hunk ./doc/Cabal.xml 1688 - Set the verbosity level (0-5). The normal level is 1; - a missing n defaults to 3. + Set the verbosity level (0-3). The normal level is 1; + a missing n defaults to 2. hunk ./doc/Cabal.xml 1696 - other options will be reported as errors, except in the case of - the configure command. + other options will be reported as errors. hunk ./doc/Cabal.xml 2243 - If a package descriptions specifies configuration flags - (see ) the package user can - control these in several ways. If none of the options below - are given, Cabal will try to find a flag assignment in the - following way. - - - For each flag specified, it will assign its default - value, evaluate all conditions with this flag assignment, - and check if all dependencies can be satisfied. If this - check succeeded, the package will be configured with those - flag assignments. - - - If dependencies were missing, the last flag (as by - the order in which the flags were introduced in the - package description) is tried with its alternative value - and so on. This continues until either an assignment is - found where all dependencies can be satisfied, or all - possible flag assignments have been tried. - - - If no suitable flag assignment could be found, the - configuration phase will fail and a list of missing - dependencies will be printed. Note that this resolution - process is exponential in the worst case (i.e., in the case - where dependencies cannot be satisfied). There are some - optimizations applied internally, but the overall complexity - remains unchanged. - - Flag assignments can be controlled with the following - command line options. + Flag assignments (see ) can be + controlled with the following command line options. hunk ./doc/Cabal.xml 2470 - These are the mostly same as the options configure step (see + These are mostly the same as the options configure step (see }