diff --git a/.gitignore b/.gitignore index ebc21507c..c787f7e46 100644 --- a/.gitignore +++ b/.gitignore @@ -37,3 +37,5 @@ gambit .python-version dist .venv +*.dmg +Gambit.app/* \ No newline at end of file diff --git a/INSTALL.md b/INSTALL.md deleted file mode 100644 index 467619a82..000000000 --- a/INSTALL.md +++ /dev/null @@ -1,138 +0,0 @@ -### General information - -Gambit uses the standard autotools mechanism for configuring and building. -This should be familiar to most users of Un\*ces and MacOS X. In general, -you just need to unpack the sources, change directory to the top level -of the sources (typically of the form gambit-X.Y.Z), and do the -usual - - ./configure - make - sudo make install - -Command-line options are available to modify the configuration process; -do `./configure --help` for information. - -By default Gambit will be installed in /usr/local. You can change this -by replacing configure step with one of the form - - ./configure --prefix=/your/path/here - -NOTE: The graphical interface relies on external calls to other -programs built in this process, especially for the computation of -equilibria. It is strongly recommended that you install the Gambit -executables to a directory in your path! - - -### Building from git repository - -If you want to live on the bleeding edge, you can get the latest -version of the Gambit sources from the Gambit repository on -github.com, via: - - git clone https://github.com/gambitproject/gambit.git - cd gambit - -After this, you will need to set up the build scripts by executing: - - aclocal - automake --add-missing - autoconf - -For this, you will need to have automake, autoconf, and libtool2 -installed on your system. - -At this point, you can then continue with the configuration and build -stages as in the previous section. - -### gambit-enumpoly - -The program gambit-enumpoly does not compile on some compilers and systems. -If you encounter problems building this, you can disable compilation using -the switch `--disable-enumpoly` at the configuration step, e.g. - - ./configure --disable-enumpoly [other options here] - -There is a related issue in the issue tracker (#288); if you encounter problems -building `gambit-enumpoly` (or want to contribute towards fixing it!) please -use that issue to post information. - - -### For Windows users - -For Windows users wanting to compile Gambit on their own, you'll need -to use either the Cygwin or MinGW environments. We do compilation and -testing of Gambit on Windows using MinGW, which can be gotten from - -http://www.mingw.org - - -### For OS X users - -OS X users should being by following the Un\*x/Linux instructions above. -This will create the command-line tools, and the graphical interface -binary called `gambit`. This graphical interface binary requires an -X server to run correctly. - -For a more native OS X experience, after completing the Un*x/Linux -instructions, additionally issue the command - - make osx-bundle - -This will create a directory Gambit.app with the graphical interface -in an application bundle. This bundle can then be copied (e.g., to -`/Applications`) and used like any other OS X application. - -wxWidgets is available, for example, via Homebrew on Mac OS X. -If you build wxWidgets yourself (see below), -be sure to tell the `./configure` step where to find the version you built -by using the `--with-wx-prefix parameter`. For example, if you install -wxWidgets into `/usr/local` (the default when you build it), configure -Gambit with - - ./configure --with-wx-prefix=/usr/local - - -### The graphical interface and wxWidgets - -Gambit requires wxWidgets version 3.1.5 or higher for the -graphical interface. See their website at - -http://www.wxwidgets.org - -to download this if you need it. Packages of this should be available -for most Un\*x users through their package managers (apt or rpm). Note -that you'll need the appropriate -dev package for wxWidgets to get the -header files needed to build Gambit. - -Un\*x users, please note that Gambit only supports the GTK port of wxWidgets. - -If wxWidgets it isn't installed in a standard place (e.g., `/usr` or -`/usr/local`), you'll need to tell configure where to find it with the -`--with-wx-prefix=PREFIX` option, for example: - - ./configure --with-wx-prefix=/home/mylogin/wx - -Finally, if you don't want to build the graphical interface, you -can either (a) simply not install wxWidgets, or (b) pass the argument -`--disable-gui` to the configure step, for example, - - ./configure --disable-gui - -This will just build the command-line tools, and will not require -a wxWidgets installation. - - -### pygambit Python extension - -Gambit is available as a Python extension module, called `pygambit`. -`pygambit` is available via PyPi and `pip`. - -If you wish to compile the extension module on your own, then you can, -from the root directory, execute - - python setup.py build - python setup.py install - -As in general with Python, it is strongly recommended to install `pygambit` -as part of a virtual environment rather than in the system's Python. diff --git a/doc/developer.build.rst b/doc/developer.build.rst index 62a8f4706..596fc6ea6 100644 --- a/doc/developer.build.rst +++ b/doc/developer.build.rst @@ -1,131 +1,178 @@ +.. _building-from-source: + Building Gambit from source =========================== -This section covers instructions for building Gambit from source. +This page covers instructions for building Gambit from source. This is for those who are interested in developing Gambit, or who want to play around with the latest features before they make it into a pre-compiled binary version. -This section requires at least some familiarity with programming. -Most users will want to stick with binary distributions; see -:ref:`section-downloading` for how to get the current version for +This page requires at least some familiarity with programming. +Most users will want to stick with released distributions; see the +:ref:`install` page for how to get the current version for your operating system. +Following the instructions here will install the Gambit CLI, GUI and Python extension (PyGambit). -General information -------------------- +The steps you will need to follow to build from source are as follows: -Gambit uses the standard autotools mechanism for configuring and building. -This should be familiar to most users of Un*ces and MacOS X. +1. Refer to the :ref:`contributor page ` which explains how to clone the Gambit repository from GitHub (you may first wish to create a fork). +2. :ref:`Install the necessary build tools and dependencies for your platform `. +3. :ref:`Follow the platform-specific instructions to build and install Gambit CLI and GUI components from source `. +4. :ref:`Build the Python extension (PyGambit) `. -If you are building from a source tarball, -you just need to unpack the sources, change directory to the top level -of the sources (typically of the form gambit-xx.y.z), and do the -usual :: +.. _source-dependencies: - ./configure - make - sudo make install +Install build tools and dependencies +------------------------------------ -Command-line options are available to modify the configuration process; -do `./configure --help` for information. Of these, the option which -may be most useful is to disable the build of the graphical interface +.. dropdown:: Install on macOS via Homebrew + :class-container: sd-border-0 + + 1. Check that you have Homebrew installed by running `brew --version`. If not, follow the instructions at `https://brew.sh/ `_. -By default Gambit will be installed in /usr/local. You can change this -by replacing configure step with one of the form :: + 2. Install build dependencies: - ./configure --prefix=/your/path/here + .. code-block:: bash -.. note:: - The graphical interface relies on external calls to other - programs built in this process, especially for the computation of - equilibria. It is strongly recommended that you install the Gambit - executables to a directory in your path! + brew install automake autoconf libtool wxwidgets + + .. note:: + If you encounter interpreter errors with autom4te, you may need to ensure + your Perl installation is correct or reinstall the autotools: + + .. code-block:: bash + + brew reinstall automake autoconf libtool wxwidgets + +.. dropdown:: Install on Linux (Debian/Ubuntu) via apt + :class-container: sd-border-0 + + 1. Update your package lists: + + .. code-block:: bash + + sudo apt update + + 2. Install general build dependencies: + + .. code-block:: bash + + sudo apt install build-essential automake autoconf libtool + + 3. Install GUI dependencies: + + .. code-block:: bash + sudo apt install libwxgtk3.2-dev -Building from git repository ----------------------------- +.. dropdown:: Install on Windows + :class-container: sd-border-0 -If you want to live on the bleeding edge, you can get the latest -version of the Gambit sources from the Gambit repository on -github.com, via :: + The recommended way to build Gambit on modern Windows is to use the + MSYS2 / MinGW-w64 environment. - git clone https://github.com/gambitproject/gambit.git - cd gambit + 1. Download and install MSYS2 from https://www.msys2.org/ and follow + the update instructions there (you will typically run ``pacman -Syu`` + and restart the MSYS2 terminal as instructed). -After this, you will need to set up the build scripts by executing :: + 2. Open the "MSYS2 MinGW 64-bit" terminal (important: use the MinGW + shell, not the plain MSYS shell). - aclocal - libtoolize - automake --add-missing - autoconf + 3. Install general build dependencies -For this, you will need to have automake, autoconf, and libtool2 -installed on your system. + .. code-block:: bash -At this point, you can then continue with the configuration and build -stages as in the previous section. + # update package DB & core packages first (may require closing/reopening the shell) + pacman -Syu -In the git repository, the branch ``master`` always points to the -latest development version. New development should in general always -be based off this branch. Branches labeled ``maintVV``, where ``VV`` -is the version number, point to the latest commit on a stable -version. + # install compiler toolchain, autotools and libtool + pacman -S --needed mingw-w64-x86_64-toolchain mingw-w64-x86_64-automake \ + mingw-w64-x86_64-autoconf mingw-w64-x86_64-libtool mingw-w64-x86_64-make + 4. Install GUI dependencies -For Windows users ------------------ + .. code-block:: bash -For Windows users wanting to compile Gambit on their own, you'll need -to use either the Cygwin or MinGW environments. We do compilation and -testing of Gambit on Windows using MinGW. + pacman -S --needed mingw-w64-x86_64-wxwidgets3.2 + .. note:: + When building for a different target (32-bit) substitute the corresponding MinGW packages (``mingw-w64-i686-*``). -For OS X users --------------- -For building the command-line tools only, one should follow the -instructions for Un*x/Linux platforms above. +.. _cli-gui-from-source: +Install CLI and GUI from source +-------------------------------- -The graphical interface and wxWidgets -------------------------------------- +Navigate to the Gambit source directory (use the "MSYS2 MinGW 64-bit" terminal on Windows) and run: -Gambit requires wxWidgets version 3.1.x or higher. -See the wxWidgets website at -``_ -to download this if you need it. Packages of this should be available -for most Un*x users through their package managers (apt or rpm). Note -that you'll need the appropriate -dev package for wxWidgets to get the -header files needed to build Gambit. +.. code-block:: bash -Un*x users, please note that Gambit at this time only supports the -GTK port of wxWidgets. + aclocal + libtoolize + automake --add-missing + autoconf + ./configure + make + # Skip this on Windows: + sudo make install -If wxWidgets it isn't installed in a standard place (e.g., /usr or -/usr/local), you'll need to tell configure where to find it with the ---with-wx-prefix=PREFIX option, for example:: +.. dropdown:: Build macOS application bundle + :class-container: sd-border-0 - ./configure --with-wx-prefix=/home/mylogin/wx + 1. Create macOS application bundle: -Finally, if you don't want to build the graphical interface, you -can either (a) simply not install wxWidgets, or (b) pass the argument ---disable-gui to the configure step, for example, :: + To create a distributable DMG file: - ./configure --disable-gui + .. code-block:: bash -This will just build the command-line tools, and will not require -a wxWidgets installation. + make osx-dmg -For OS X users, after the usual ``make`` step, run + 2. Install the application: - make osx-bundle + After creating the DMG file, open it and drag the Gambit application to your Applications folder. -This produces an application ``Gambit.app`` in the current directory, -which can be run from its current location, or copied elsewhere in the -disk (such as ``/Applications``). The application bundle includes the -command-line executables. +.. dropdown:: Creating a Windows installer + :class-container: sd-border-0 + 1. Create a ``.msi`` installer. This requires the `Wix toolset `__. + .. code-block:: powershell + + make msw-msi + + 2. Install the application: + + Run the generated ``gambit-X.Y.Z.msi`` file to install Gambit on your system. + +.. note:: + Command-line options are available to modify the configuration process; + do `./configure --help` for information. Of these, the option which + may be most useful is to disable the build of the graphical interface. + + By default Gambit will be installed in /usr/local. You can change this + by replacing configure step with one of the form :: + + ./configure --prefix=/your/path/here + +.. note:: + If you don't want to build the graphical interface, you can pass the argument ``--disable-gui`` to the configure step, for example:: + + ./configure --disable-gui + +.. warning:: + If wxWidgets isn't installed in a standard place (e.g., ``/usr`` or + ``/usr/local``), you'll need to tell ``configure`` where to find it with the + ``--with-wx-prefix=PREFIX`` option, for example:: + + ./configure --with-wx-prefix=/home/mylogin/wx + +.. warning:: + The graphical interface relies on external calls to other + programs built in this process, especially for the computation of + equilibria. It is strongly recommended that you install the Gambit + executables to a directory in your path! .. _build-python: @@ -133,14 +180,16 @@ Building the Python extension ----------------------------- The :ref:`pygambit Python package ` is in ``src/pygambit`` -in the Gambit source tree. -Building the extension follows the standard approach. -From the **root directory of the source tree** execute +in the Gambit source tree. We recommend to install `pygambit` +as part of a virtual environment rather than in the system's Python. +Use `pip` to install from the **root directory of the source tree**, optionally including the `-e` flag for an editable install: + +.. code-block:: bash - python -m pip install . + python -m pip install . There is a set of test cases in `src/pygambit/tests`, which can be run -using `nose2`. +using `pytest`. Once installed, simply ``import pygambit`` in your Python shell or script to get started. diff --git a/doc/developer.contributing.rst b/doc/developer.contributing.rst index daf27fcac..07ae2e83e 100644 --- a/doc/developer.contributing.rst +++ b/doc/developer.contributing.rst @@ -1,7 +1,7 @@ -Contributing to the Gambit Project -================================== +Contributing to Gambit +====================== -This section provides guidelines for contributing to the Gambit project, including how to report bugs, suggest features, and contribute code. +This section provides guidelines for contributing to Gambit, including how to report bugs, suggest features, and contribute code. It includes information relevant to both core developers and external contributors. GitHub issues @@ -22,12 +22,19 @@ When reporting a bug, please be sure to include the following: sample game file or files if appropriate; it is often helpful to simplify the game if possible. +.. _contributing-code: + Contributing code ---------------- Gambit is an open-source project, and contributions are welcome from anyone. The project is hosted on GitHub, and contributions can be made via pull requests following the standard GitHub workflow. +In the git repository, the branch ``master`` always points to the +latest development version. New development should in general always +be based off this branch. Branches labeled ``maintX_Y``, where ``X`` is the major version number and ``Y`` is the minor version number, point to the latest commit on a stable +version. + 1. To get started contributing code in the `Gambit GitHub repo `__, do one of the following: - Core developers: request contributor access from one of the `team `__ diff --git a/doc/gui.rst b/doc/gui.rst index 361681c40..83e6e1009 100644 --- a/doc/gui.rst +++ b/doc/gui.rst @@ -4,6 +4,8 @@ GUI *** +See installation instructions in the :ref:`install-cli-gui` section. + Gambit's graphical user interface provides an "integrated development environment" to help visually construct games and to investigate their main strategic features. @@ -25,7 +27,6 @@ To build larger games or to explore parameter spaces of a game systematically, it is recommended to use :ref:`the Python package `. - .. toctree:: :maxdepth: 2 diff --git a/doc/index.rst b/doc/index.rst index 2fcb284f3..22560eca3 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -4,29 +4,28 @@ Gambit: User documentation **Gambit** is a library of game theory software and tools for the construction and analysis of finite extensive and strategic games. +We recommended most new users install the PyGambit Python package and read the associated documentation, which includes tutorials and a complete API reference. .. grid:: - .. grid-item-card:: Python user guide + .. grid-item-card:: Installing Gambit :columns: 6 - An introduction to using the ``pygambit`` package - in Python. + Get started by installing Gambit. PyGambit quickstart: ``pip install pygambit`` - .. button-ref:: pygambit-user + .. button-ref:: install :ref-type: ref :click-parent: :color: secondary :expand: - .. grid-item-card:: Python API reference + .. grid-item-card:: PyGambit Python package :columns: 6 - The complete reference to all the functionality - of ``pygambit``. + Create games and compute equilibria with the PyGambit package. - .. button-ref:: pygambit-api + .. button-ref:: pygambit :ref-type: ref :click-parent: :color: secondary @@ -36,8 +35,7 @@ construction and analysis of finite extensive and strategic games. .. grid-item-card:: Command-line tools :columns: 6 - All Gambit's methods for equilibrium computation are - available via command-line programs. + Quickly compute equilibria with the Gambit command-line tools. .. button-ref:: command-line :ref-type: ref @@ -63,6 +61,7 @@ construction and analysis of finite extensive and strategic games. :maxdepth: 1 intro + install pygambit tools gui diff --git a/doc/install.rst b/doc/install.rst new file mode 100644 index 000000000..8af5e8c10 --- /dev/null +++ b/doc/install.rst @@ -0,0 +1,113 @@ +.. _install: + + +Install +======= + +Users installing Gambit have several options depending on their needs and their operating system. +We recommended most new users install the PyGambit package and read the :ref:`PyGambit documentation `. + +Developers & contributors should refer to the :ref:`developer docs ` which contain guides for building Gambit from source and contributing to the project. + +Installing PyGambit +------------------- + +PyGambit is available on `PyPI `_. We recommend installing it into a Python virtual environment via `pip`:: + + pip install pygambit + + +Older releases can be installed by specifying the version number. +Visit the `Gambit releases page on GitHub `_ for information on older versions. + +.. _install-cli-gui: + +Installing Gambit GUI & CLI tools +--------------------------------- + +To install the Gambit :ref:`GUI ` and :ref:`CLI tools `, visit the `Gambit releases page on GitHub `_ and download the appropriate installer or package for your operating system. +Each release includes pre-built binaries for Windows, macOS, and Linux distributions, accessible under the "Assets" section of each release. + +.. dropdown:: Install on macOS with disk image + :class-container: sd-border-0 + + 1. **Download the .dmg installer:** + + Visit the `Gambit releases page on GitHub `_ and download the `.dmg` file for the version of Gambit you wish to install. + + 2. **Install the application:** + + Double click the `.dmg` file to mount it, then drag the Gambit application to your Applications folder. + + .. warning:: + You may need to adjust your macOS security settings to allow the installation of applications from unidentified developers. + + This can be done in ``System Preferences > Security & Privacy`` (see `Apple's documentation `_ for more details). + + If your administration privileges prevent this, try the Homebrew installation method below, or build from source as described in the :ref:`developer build instructions `. + +.. dropdown:: Install on macOS via Homebrew + :class-container: sd-border-0 + + 1. Check that you have Homebrew installed by running `brew --version`. If not, follow the instructions at `https://brew.sh/ `_. + + 2. Install Gambit using Homebrew: + + .. code-block:: bash + + brew install gambit + + .. warning:: + Homebrew installation has not been set up or tested by the Gambit development team. + +.. dropdown:: Install on Linux or macOS from source tarball + :class-container: sd-border-0 + + 1. **Download the source tarball:** + + Visit the `Gambit releases page on GitHub `_ and download the source tarball for the version of Gambit you wish to install. + + 2. **Extract the tarball:** + + Once downloaded, extract the tarball using the following command: + + .. code-block:: bash + + tar -xzf gambit-*.tar.gz + + 3. **Build and install Gambit:** + + Navigate to the extracted directory and run: + + .. code-block:: bash + + ./configure + make + sudo make install + + .. note:: + Command-line options are available to modify the configuration process; + do `./configure --help` for information. Of these, the option which + may be most useful is to disable the build of the graphical interface. + + By default Gambit will be installed in /usr/local. You can change this + by replacing configure step with one of the form :: + + `./configure --prefix=/your/path/here` + + .. warning:: + The graphical interface relies on external calls to other + programs built in this process, especially for the computation of + equilibria. It is strongly recommended that you install the Gambit + executables to a directory in your path! + +.. dropdown:: Install on Windows with installer + :class-container: sd-border-0 + + 1. **Download the installer:** + + Visit the `Gambit releases page on GitHub `_ and download the `.msi`. + + 2. **Run the installer:** + + Double click the downloaded `.msi` file and follow the on-screen instructions to complete the installation. \ No newline at end of file diff --git a/doc/pygambit.rst b/doc/pygambit.rst index 556a80afb..853978bd1 100644 --- a/doc/pygambit.rst +++ b/doc/pygambit.rst @@ -4,15 +4,7 @@ PyGambit ======== -Gambit provides a Python package, ``pygambit``, which is available on `PyPI -`_. - -Installation ------------- - -To install the package, use the following command:: - - pip install pygambit +See installation instructions in the :ref:`install` section. .. toctree:: :maxdepth: 2 diff --git a/doc/tools.rst b/doc/tools.rst index 542c5bf4e..8a3643b79 100644 --- a/doc/tools.rst +++ b/doc/tools.rst @@ -4,6 +4,8 @@ CLI *** +See installation instructions in the :ref:`install-cli-gui` section. + Gambit provides command-line interfaces for each method for computing Nash equilibria. These are suitable for scripting or calling from other programs. This chapter describes the use of these programs.