Skip to content

Commit b89df81

Browse files
platipusicaplatipusica
authored
Update new_project.txt
1 parent 077dab5 commit b89df81

File tree

1 file changed

+166
-85
lines changed

1 file changed

+166
-85
lines changed

‎intro/new_project.txt

Lines changed: 166 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,122 +1,203 @@
1-
==================
2-
Creating a project
3-
==================
1+
================================
2+
How to install Jam.py on Windows
3+
================================
4+
5+
.. admonition:: Adapted from `Django Docs`_
6+
7+
The below document is adopted from `Django Docs`_.
8+
9+
This document will guide you through installing Python 3.x and Jam.py on
10+
Windows. It also provides instructions for setting up a virtual environment,
11+
which makes it easier to work on Python projects. This is meant as a beginner's
12+
guide for users working on Jam.py projects and does not reflect how Jam.py
13+
should be installed when developing patches for Jam.py itself.
14+
15+
The steps in this guide have been tested with Windows 10. In other
16+
versions, the steps would be similar. You will need to be familiar with using
17+
the Windows command prompt.
18+
19+
20+
.. _Django Docs: https://docs.djangoproject.com/
21+
22+
Install Python
23+
==============
24+
25+
Jam.py is a Python web framework, thus requiring Python to be installed on your
26+
machine. At the time of writing, Python 3.8 is the latest version.
27+
28+
To install Python on your machine go to https://www.python.org/downloads/. The
29+
website should offer you a download button for the latest Python version.
30+
Download the executable installer and run it. Check the boxes next to "Install
31+
launcher for all users (recommended)" then click "Install Now".
32+
33+
After installation, open the command prompt and check that the Python version
34+
matches the version you installed by executing::
35+
36+
...\> python --version
37+
38+
39+
About ``pip``
40+
=============
41+
42+
`pip`_ is a package manager for Python and is included by default with the
43+
Python installer. It helps to install and uninstall Python packages
44+
(such as Jam.py!). For the rest of the installation, we'll use ``pip`` to
45+
install Python packages from the command line.
46+
47+
.. _pip: https://pypi.org/project/pip/
48+
49+
.. _virtualenvironment:
50+
51+
Setting up a virtual environment
52+
================================
53+
54+
It is best practice to provide a dedicated environment for each Jam.py project
55+
you create. There are many options to manage environments and packages within
56+
the Python ecosystem, some of which are recommended in the `Python
57+
documentation <https://packaging.python.org/guides/tool-recommendations/>`_.
58+
59+
To create a virtual environment for your project, open a new command prompt,
60+
navigate to the folder where you want to create your project and then enter the
61+
following::
62+
63+
...\> python -m venv project-name
64+
65+
This will create a folder called 'project-name' if it does not already exist
66+
and set up the virtual environment. To activate the environment, run::
67+
68+
...\> project-name\Scripts\activate.bat
69+
70+
The virtual environment will be activated and you'll see "(project-name)" next
71+
to the command prompt to designate that. Each time you start a new command
72+
prompt, you'll need to activate the environment again.
73+
74+
Install Jam.py
75+
==============
76+
77+
Jam.py can be installed easily using ``pip`` within your virtual environment.
78+
79+
In the command prompt, ensure your virtual environment is active, and execute
80+
the following command::
81+
82+
...\> python -m pip install jam.py
83+
84+
85+
For a forked Jam.py with the latest patches, use::
86+
87+
...\> python -m pip install jam.py-v5
88+
89+
90+
This will download and install the latest Jam.py release.
91+
92+
After the installation has completed, you can verify your Jam.py installation
93+
by executing ``pip list`` in the command prompt.
94+
95+
96+
Create a new project
97+
====================
498

599
Create a new directory.
6100

7-
Go into the directory and run from command line:
101+
Go into the directory and run from command line::
8102

9-
.. code-block:: console
103+
...\>python ..\project-name\Scripts\jam-project.py
10104

11-
$ jam-project.py
12105

106+
To start the Jam.py web server run ``server.py`` script::
13107

14-
The following files and folders will be created in the directory::
15108

16-
/
17-
css/
18-
js/
19-
img/
20-
reports/
21-
static/
22-
admin.sqlite
23-
server.py
24-
index.html
25-
wsgi.py
109+
...\>python server.py
26110

27111

28-
To start the Jam.py web server run ``server.py`` script.
112+
Click "Allow" for public and private networks to access this app.
29113

30114

31-
.. code-block:: console
115+
Common pitfalls
116+
===============
32117

33-
$ ./server.py
34118

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

36-
.. note::
37-
You can specify a port as parameter, for example
38-
39-
.. code-block:: console
40-
41-
$ ./server.py 8081
42-
43-
By default, the port is 8080. If you specify another port, you need to
44-
use it in your browser in the next steps.
123+
...\> set http_proxy=http://username:password@proxyserver:proxyport
124+
...\> set https_proxy=https://username:password@proxyserver:proxyport
45125

46126

47-
Open a Web browser and go to “/builder.html” on your local domain – e.g.:
127+
* If your Administrator prohibited setting up a virtual environment, it
128+
is still possible to install Jam.py as follows::
48129

130+
...\> python -m pip install jam.py
131+
132+
133+
For a forked Jam.py with the latest patches, use::
134+
135+
...\> python -m pip install jam.py-v5
49136

50-
.. code-block:: console
51137

52-
127.0.0.1:8080/builder.html
53-
54138

55-
You should see the language selection dialog. This defines the language used for the
56-
user interface. You can select the language from the list of default languages, or
57-
import your own, using the "folder" icon to the right of the input field. See the
58-
:doc:`Language support </admin/language_support>` page for more information.
59-
Select your language and press the OK button.
139+
This will download and install the latest Jam.py release.
60140

61-
.. image:: _images/lang.png
62-
:alt: Jam.py language dialog
141+
After the installation has completed, you can verify your Jam.py installation
142+
by executing ``pip list`` in the command prompt.
63143

64-
In the New project dialog box fill in:
144+
However, running ``jam-project.py`` will fail since it is not in the path. Check
145+
the installation folder::
65146

66-
* **Caption** - the project name that will appear to users.
67-
* **Name** - the name of project (task) that will be used in the code (Python or JS)
68-
to get access to the task object. This should be a short and valid python identifier.
69-
This name is also used as a prefix when creating a table in the project database.
70-
* **DB type** - select a database type. If the database is not Sqlite, it must be
71-
created in advance and its attributes should be entered in the
72-
corresponding form fields.
73-
To see examples of Database setup, follow the :doc:`link </admin/project/database>`.
147+
...\> python -m site --user-site
74148

75-
.. image:: _images/project_params.png
76-
:align: center
77-
:alt: New project setup
149+
The output might be similar to the following::
78150

79-
When you press OK, the connection to the database will be checked, and in case
80-
of failure an error message will be displayed.
151+
C:\Users\youruser\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\site-packages
81152

82-
.. note::
83153

84-
Please note the following requirements:
85-
86-
* To use a **FireBird** database, the python ``fdb`` library must be installed.
87-
* **PostgreSQL** requires the ``psycopg2`` library.
88-
* **MySQL** requires the ``MySQLdb`` for Python 2.x or ``mysqlclient`` for Python 3.x.
89-
* **Oracle** requires the ``cx_Oracle`` library.
90-
* **MSSQL** requires the ``pymssql`` library.
91-
* To generate reports, **LibreOffice** must be installed.
92-
93-
.. note::
94154

95-
For a **SQLite** database, when an item field is deleted or renamed, or foreign
96-
key is created,
97-
:doc:`Application builder </admin/index>`,
98-
creates a new table and copies records from the old one into it.
99-
100-
For **SQLite** database, Jam.py doesn’t support importing of metadata into an
101-
existing project (project with tables in the database).
102-
You can only import metadata into a new project.
155+
Replace ``site-packages`` at the end of above line with ``Scripts``::
156+
157+
...\> dir C:\Users\youruser\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\Scripts
158+
159+
160+
The output might be similar to the following::
161+
162+
...\> Directory of C:\Users\yourser\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\Scripts
163+
164+
13/04/2023 02:59 PM <DIR> .
165+
13/04/2023 02:59 PM <DIR> ..
166+
13/04/2023 02:59 PM 1,087 jam-project.py
167+
1 File(s) 1,087 bytes
168+
2 Dir(s) 177,027,321,856 bytes free
169+
170+
171+
172+
Create the new folder somewhere and run ``jam-project`` from from it::
173+
174+
...\> python C:\Users\youruser\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\Scripts\jam-project.py
175+
176+
177+
Run the new project::
178+
179+
...\> python server.py
180+
181+
182+
Installing WLS
183+
==============
184+
103185

104-
If all goes well, a new project will be created and the project tree will appear
105-
in the Application builder.
186+
Invoking installation::
106187

188+
...\> wsl --install
107189

108-
.. image:: _images/adm_new_project.png
109-
:align: center
110-
:alt: Jam.py Application builder
111190

112-
Now, to see the project itself, create a new page in the browser and type in the
113-
address bar:
114191

115-
.. code-block:: console
192+
The output might be similar to the following::
116193

117-
127.0.0.1:8080
194+
Installing: Virtual Machine Platform
195+
Virtual Machine Platform has been installed.
196+
Installing: Windows Subsystem for Linux
197+
Windows Subsystem for Linux has been installed.
198+
Installing: Ubuntu
199+
Ubuntu has been installed.
200+
The requested operation is successful. Changes will not be effective until the system is rebooted.
118201

119202

120-
.. image:: _images/empty_project.png
121-
:align: center
122-
:alt: Jam.py project
203+
Now, we have a development environment with Ubuntu, and we can proceed with Jam.py installation as usual for Linux.

0 commit comments

Comments
 (0)