<type>documentation</type>
<domain>proj</domain>
<id>creating-a-project</id>
<title>Creating a Project</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

To create a new project, use the ``New Project`` in the ``Project`` menu. This prompts to
save any changes to your currently open project and then creates a new untitled project.
You can then save your project to disk from the ``Project`` menu.

**Project Types**

In the ``New Project`` dialog you will be able to select from among a number of different
project types, including:

``Empty Python Project`` creates a new empty project that can be manually configured
for any Python project.
  
``Create New Virtualenv`` runs virtualenv to create a new virtual environment
to use with the project.  You will be prompted for the virtualenv name, the 
base Python installation to use, and the parent directory for the new virtualenv.
See `Using Wing with virtualenv <ref:howtos/virtualenv>`__ for more information.
  
``Use Existing Virtualenv`` creates a new empty project using a previously
created virtualenv.
  
~~~if WINGPRO:
``Connect to Remote Host via SSH`` sets up a project that will work with source 
code that resides on a remote host, container, or virtual machine. See `Remote Hosts
<ref:proj/remote-hosts>`__ for more information.
  
``Connect to Vagrant`` sets up a project that works with source code that is stored 
in a `Vagrant <ref:howtos/vagrant>`__ container.
  
``Connect to WSL`` sets up a project that works with source code that is stored on 
a Linux installation running under `Windows Subsystem for Linux <ref:howtos/wsl>`__.
~~~

A number of other project types are offered as well, for working with specific frameworks
and tools documented in `How-Tos <ref:howtos>`__, such as `Django <ref:howtos/django>`__,
`Jupyter <ref:howtos/jupyter>`__, `matplotlib <ref:howtos/jupyter>`__, `Raspberry Pi
<ref:howtos/raspberry>`__, and so forth.

Each project type creates a new untitled project, performs the necessary basic project 
configuration, and then displays documentation for the selected project type.

**Python Environment**

When you create a new project, you should make sure that the ``Python Executable``,
``Python Path`` (if your code modifies ``sys.path``) and other values in `Project
Properties <ref:proj/project-properties>`__ match the Python environment needed by
your code. This allows Wing to find and inspect all the modules your code imports, so that
editor and debugger features work properly.

**Adding Files and Directories**

Adding your source files to the project tells Wing which files you are working on,
which is important for searching, ``Open From Project``, and other features.  Usually
only the source base you are working on should be added to the project, while Python's
standard libraries and other frameworks and libraries used by your code can be
left out of the project and instead found, as needed, through the ``Python Path``.

The best way to add code is ``Add Existing Directory`` in the ``Project`` menu. This
allows you to control which files to include, and whether or not sub-directories are
included. The list of files shown in the project updates as files matching the criteria
are added and removed on disk.

Individual files can be added with ``Add Current File`` and ``Add Existing File``.

``Add New File`` can be used to create a new file and simultaneously add
it to your project.

A subset of these options can be accessed from the context menu that appears when
right-clicking on the ``Project`` tool.

**Removing or Omitting Files and Directories**

To remove a specific file or directory, select it and use ``Remove Selected Entry`` in the
``Project`` menu or ``Remove/Exclude From Project`` in the right-click context menu on the
``Project`` tool.

If the removed file or directory is part of another directory that has been added to the
project, the removal is remembered as an exclusion that can be cleared from ``Directory
Properties``, which are accessed by right clicking on the parent directory in the
``Project`` tool.

**Saving a New Project**

To save a new project, use ``Save Project`` in the ``Project`` menu. Once a project file
has been saved the first time, it will be re-saved automatically as you work with Wing.
