============
Installation
============

Install python
==============

Jam.py requires python. If it is not installed you can get the latest 
version of Python at https://www.python.org/download/ 

You can use the following versions of Python with Jam.py:

Python 2

* Python 2.7 and newer

Python 3

* Python 3.4 and newer


You can verify that Python is installed by typing python from your shell; 
you should see something like::

    Python 2.7.12 (default, Nov 19 2016, 06:48:10) 
    [GCC 5.4.0 20160609] on linux2
    Type "help", "copyright", "credits" or "license" for more information.
    >>> 
    
If Python 2 and Python 3 are installed try to type python3::

    Python 3.5.2 (default, Nov 17 2016, 17:05:23) 
    [GCC 5.4.0 20160609] on linux
    Type "help", "copyright", "credits" or "license" for more information.
    >>>     

Install Jam.py
====================

Installing an official release with `pip`
-----------------------------------------

This is the recommended way to install Jam.py.

1. Install pip_. The easiest is to use the `standalone pip installer`_. If your
   distribution already has ``pip`` installed, you might need to update it if
   it's outdated. (If it's outdated, you'll know because installation won't
   work.)

2. If you're using Linux, Mac OS X or some other flavor of Unix, enter the
   command 
   
   .. code-block:: console
   
    sudo pip install jam.py 
    
   at the shell prompt. 
   
   If you're using Windows, start a command shell with administrator privileges 
   and run the command 
   
   .. code-block:: console
   
    pip install jam.py 
   
   This will install Jam.py in your Python installation's ``site-packages`` directory.


.. _pip: http://www.pip-installer.org/
.. _standalone pip installer: http://www.pip-installer.org/en/latest/installing.html#install-pip


Installing an official release manually
---------------------------------------

1. Download the package archive. 

2. Create a new directory and unpack the archive there. 

3. Go into the directory and run the setup command from command line

.. code-block:: console

   $ python setup.py install
    
This will install Jam.py in your Python installation’s site-packages directory.

.. note::
	on some unix like systems you may need to switch to root or run: 
	sudo python setup.py install
	
	
Setting up a virtual environment
================================

It is best practice to provide a dedicated environment for each Jam.py project
you create. There are many options to manage environments and packages within
the Python ecosystem, some of which are recommended in the `Python
documentation <https://packaging.python.org/guides/tool-recommendations/>`_.

To create a virtual environment for your project, open a new command prompt,
navigate to the folder where you want to create your project and then enter the
following::

    ...\> py -m venv project-name

This will create a folder called 'project-name' if it does not already exist
and set up the virtual environment. To activate the environment, run::

    ...\> project-name\Scripts\activate.bat

The virtual environment will be activated and you'll see "(project-name)" next
to the command prompt to designate that. Each time you start a new command
prompt, you'll need to activate the environment again.

Install Jam.py
==============

Jam.py can be installed easily using ``pip`` within your virtual environment.

In the command prompt, ensure your virtual environment is active, and execute
the following command::

    ...\> py -m pip install jam.py

This will download and install the latest Jam.py release.

After the installation has completed, you can verify your Jam.py installation
by executing ``pip list`` in the command prompt.



Common pitfalls
===============


* If you are connecting to the internet behind a proxy, there might be problems
  in running the command ``py -m pip install Jam.py``. Set the environment
  variables for proxy configuration in the command prompt as follows::

    ...\> set http_proxy=http://username:password@proxyserver:proxyport
    ...\> set https_proxy=https://username:password@proxyserver:proxyport


* If your Administrator prohibited setting up a virtual environment, it 
  is still possible to install Jam.py as follows::

    ...\> python -m pip install jam.py


    
  This will download and install the latest Jam.py release.

  After the installation has completed, you can verify your Jam.py installation
  by executing ``pip list`` in the command prompt.

  However, running ``jam-project.py`` will fail since it is not in the path. Check
  the installation folder::

    ...\> python -m site --user-site

  The output might be similar to below::

    C:\Users\youruser\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\site-packages



  Replace ``site-packages`` at the end of above line with ``Scripts``::

    ...\> dir C:\Users\youruser\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\Scripts


  The output might be similar to below::

    ...\> Directory of C:\Users\yourser\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\Scripts

        13/04/2023  02:59 PM    <DIR>          .
        13/04/2023  02:59 PM    <DIR>          ..
        13/04/2023  02:59 PM             1,087 jam-project.py
                       1 File(s)          1,087 bytes
                       2 Dir(s)  177,027,321,856 bytes free



  Create the new folder somewhere and run ``jam-project`` from from it::

    ...\> python C:\Users\youruser\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\Scripts\jam-project.py


  Run the new project::

    ...\> python server.py