From abaaad2bfaf5f5297f00c09357da9b9120ae5ca0 Mon Sep 17 00:00:00 2001
From: Mike Pilgrem <mpilgrem@users.noreply.github.com>
Date: Sat, 15 Mar 2025 20:30:09 +0000
Subject: [PATCH] Complete the documentation of main-is field
Explains the use of GHC's `-main-is` option in Cabal files, when the usual convention of `Main.main` is not being followed.
(cherry picked from commit f2d90986bf05c45ba55f80dab25d3b8254184544)
---
doc/cabal-package-description-file.rst | 38 ++++++++++++++++++++------
1 file changed, 29 insertions(+), 9 deletions(-)
diff --git a/doc/cabal-package-description-file.rst b/doc/cabal-package-description-file.rst
index 6ae467b477..1aed08d517 100644
--- a/doc/cabal-package-description-file.rst
+++ b/doc/cabal-package-description-file.rst
@@ -1028,12 +1028,32 @@ build information fields (see the section on `build information`_).
.. pkg-field:: main-is: filename (required)
- The name of the ``.hs`` or ``.lhs`` file containing the ``Main``
- module. Note that it is the ``.hs`` filename that must be listed,
- even if that file is generated using a preprocessor. The source file
- must be relative to one of the directories listed in
- :pkg-field:`hs-source-dirs`. Further, while the name of the file may
- vary, the module itself must be named ``Main``.
+ By convention, a Haskell program must have a module called ``Main`` which
+ exports an IO action named ``main``. When the program is executed, the
+ action is performed. This field specifies the name of the ``.hs`` or
+ ``.lhs`` source file containing that module. It is the ``.hs`` filename that
+ must be listed, even if that file is generated using a preprocessor. The
+ file must be relative to one of the directories listed in
+ :pkg-field:`hs-source-dirs`.
+
+ Further, while the name of the source file may vary, if the convention is
+ being followed, the module itself must be named ``Main`` and export
+ ``main``.
+
+ However, GHC's ``-main-is`` option can be used to change the name of the
+ relevant IO action. For example, if source file ``MyMainSourceFile.hs``
+ contains a module named ``MyMainModule`` exporting ``myMainFunc`` and that
+ is to be the relevant IO action, you can specify:
+
+ ::
+
+ executable my-app
+ main-is: MyMainSourceFile.hs
+ ghc-options: -main-is MyMainModule.myMainFunc
+ build-depends:
+ base
+ default-language: Haskell2010
+
Starting with ``cabal-version: 1.18`` this field supports
specifying a C, C++, or objC source file as the main entry point.
@@ -1090,7 +1110,7 @@ field.
even if that file is generated using a preprocessor. The source file
must be relative to one of the directories listed in
:pkg-field:`hs-source-dirs`. This field is analogous to the ``main-is`` field
- of an executable section.
+ of an executable section; see that documentation for further information.
Test suites using the ``detailed-0.9`` interface are modules exporting
the symbol ``tests :: IO [Test]``. The ``Test`` type is exported by the
@@ -1249,8 +1269,8 @@ standard output and error channels.
even if that file is generated using a preprocessor. The source file
must be relative to one of the directories listed in
:pkg-field:`hs-source-dirs`. This field is analogous to the ``main-is``
- field of an executable section. Further, while the name of the file may
- vary, the module itself must be named ``Main``.
+ field of an executable section; see that documentation for further
+ information.
Example:
"""""""""""""""""""""""""""""""""""""""""""""""""""""""
--
GitLab