204 lines
7 KiB
ReStructuredText
204 lines
7 KiB
ReStructuredText
|
|
.. highlight:: sh
|
|
|
|
Create a New Project
|
|
====================
|
|
|
|
Now that you've setup your development environment, you're ready to create a
|
|
new Rattail-based project.
|
|
|
|
.. note::
|
|
If you wish to simply install and run this rattail-tutorial project,
|
|
*instead* of creating a new project for yourself, please keep reading. This
|
|
document aims to address both use cases. However you can skip ahead to
|
|
:ref:`mkvirtualenv`.
|
|
|
|
Note again that while Rattail is a project in itself, your app is yet another
|
|
project, which is "based" on Rattail but otherwise has a life of its own. It
|
|
is *not* a "fork" of Rattail but intsead uses Rattail as a library.
|
|
|
|
Notes About Names
|
|
-----------------
|
|
|
|
There are some points to be made here, regarding project names.
|
|
|
|
First point has to do with the "types" of names involved. Really there are 3:
|
|
|
|
* "repo" name
|
|
* "project" name
|
|
* "package" name
|
|
|
|
What we're calling "repo" name here, refers to the so-called "slug" name for
|
|
the repo, e.g. the actual folder name for the repo on disk.
|
|
|
|
What we're calling "project" name here, refers to the "official" project name,
|
|
e.g. as it might be registered on PyPI or generally referenced in
|
|
documentation, etc.
|
|
|
|
What we're calling "package" name here, refers to the actual name of the Python
|
|
package contained within the project.
|
|
|
|
And there technically is a 4th, the "virtualenv" name. This refers to the
|
|
Python virtual environment you will create, within which you will install your
|
|
project. This virtualenv name need not be related necessarily, to your project
|
|
name, but in practice it usually would be. In some cases you may have multiple
|
|
virtualenvs and each must of course get a unique name.
|
|
|
|
Some examples will surely help.
|
|
|
|
.. todo::
|
|
should really have a table instead of lists here?
|
|
|
|
Example Project: Poser
|
|
|
|
* repo name: poser
|
|
* project name: Poser
|
|
* package name: poser
|
|
|
|
Example Project: rattail-tutorial
|
|
|
|
* repo name: rattail-tutorial
|
|
* project name: rattail-tutorial
|
|
* package name: rattut
|
|
|
|
Note how the "Poser" name is much more friendly and homogenous as compared to
|
|
the "rattail-tutorial" name, when considering all 3 "types" of names involved.
|
|
Really "rattail-tutorial" is not an example of a good name per se, but it was
|
|
given to this project for other reasons.
|
|
|
|
This sort of brings us to the second point about names, which is that they
|
|
*should* be "good" generally speaking. You ideally would want a name more like
|
|
"Poser" in that it's simple and easily recognizable, etc.
|
|
|
|
.. todo::
|
|
link to "how to name project" doc
|
|
(https://rattailproject.org/moin/LilSnippets/ProjectNaming)
|
|
|
|
.. _mkvirtualenv:
|
|
|
|
Creating the Virtual Environment
|
|
--------------------------------
|
|
|
|
As mentioned above, the name you give your virtual environment is really up to
|
|
you, and needn't "match" your project name etc.
|
|
|
|
Let's assume for a moment that you are creating a new project (described next)
|
|
named "Poser" - you likely will want to make a virtualenv named "poser" also::
|
|
|
|
mkvirtualenv --python=/usr/bin/python3 poser
|
|
|
|
Note that you should specify the path to your Python 3 executable, to avoid
|
|
using the "default" which is likely still Python 2 at this time.
|
|
|
|
For the sake of this tutorial, we'll be using the "rattut" env name::
|
|
|
|
mkvirtualenv --python=/usr/bin/python3 rattut
|
|
|
|
Please note that pretty much all subsequent commands shown, will assume your
|
|
virtual environment (regardless what you named it) is currently *active*. It
|
|
should be obvious when a virtualenv is active, since it should modify the shell
|
|
prompt to reflect that.
|
|
|
|
If you do need to deactivate your current virtualenv, you can do that with::
|
|
|
|
deactivate
|
|
|
|
And then to re-activate your virtualenv you do::
|
|
|
|
workon rattut
|
|
|
|
Or maybe ``workon poser`` etc., whatever named env you want to activate.
|
|
|
|
Installing Rattail Packages
|
|
---------------------------
|
|
|
|
At this point you have an "empty" virtual environment, to which we will now
|
|
install some Rattail software packages.
|
|
|
|
If you are wanting to create a new project for yourself, then the only thing
|
|
you must do for this step is::
|
|
|
|
pip install Tailbone
|
|
|
|
However if you're not wanting a new project, but wish to run this
|
|
rattail-tutorial app instead, you should do this::
|
|
|
|
mkdir -p ~/src
|
|
cd ~/src
|
|
git clone https://rattailproject.org/git/rattail-tutorial.git
|
|
pip install -e rattail-tutorial
|
|
|
|
Creating the Project
|
|
--------------------
|
|
|
|
If you're just wanting to run the rattail-tutorial app you can skip this step.
|
|
|
|
First of all you should change directory to wherever you want to create the
|
|
actual project source folder. Rattail docs will generally assume that's at
|
|
``~/src`` in which case you should do something like::
|
|
|
|
mkdir -p ~/src
|
|
cd ~/src
|
|
|
|
Remember all that talk about names, up above? Well now you will be specifying
|
|
a *single* name when creating your project. In practice the name you provide:
|
|
|
|
* should be lower-cased
|
|
* will be used as-is for the "repo" name
|
|
* will be capitalized (and weird chars replaced) to obtain "project" name
|
|
* will be used as-is for the "package" name, except weird chars replaced by "_"
|
|
|
|
Got all that straight? If not, no worries, just try this a few times and see
|
|
what you end up with. Assuming you did want the project name "Poser" you would
|
|
run the command::
|
|
|
|
pcreate -s rattail poser
|
|
|
|
This will use the "scaffold" (basically, set of templates) which is named
|
|
"rattail" to generate a new folder containing files which define a new "Poser"
|
|
project, within the "poser" folder under current directory.
|
|
|
|
Since this tutorial project is named "rattail-tutorial" and there's no possible
|
|
way for the scaffold to know that we want to use "rattut" as the Python package
|
|
name, we had to simply "pick our poison" when generating the initial tutorial
|
|
project. In other words we did::
|
|
|
|
pcreate -s rattail rattail-tutorial
|
|
|
|
Note that per the above rules, what the scaffold assumed by default was:
|
|
|
|
* repo name was "rattail-tutorial"
|
|
* project name was "Rattail_tutorial"
|
|
* package name was "rattail_tutorial"
|
|
|
|
We'll clean that up a bit shortly, but first let's start Git tracking.
|
|
|
|
Making a Git Repo
|
|
-----------------
|
|
|
|
We never want to start a new project without also starting a proper Git repo
|
|
for it. We will want to be able to ``git push`` the code to a central
|
|
location, e.g. GitHub or similar.
|
|
|
|
Change directory to your new project's source repo folder and then initialize::
|
|
|
|
cd ~/src/rattail-tutorial
|
|
git init
|
|
|
|
We also want our first commit to include all the generated code so far::
|
|
|
|
git add .
|
|
git commit -m "Initial content as generated from project scaffold"
|
|
|
|
Now we'll establish our upstream and do our first push. How exactly you go
|
|
about this may vary, and certainly the commands shown here will *not* work for
|
|
you as-is, since your "origin" at least will need to be different::
|
|
|
|
git remote add origin git@rattailproject.org:/srv/git/rattail-tutorial.git
|
|
git push --set-upstream origin master
|
|
|
|
And finally, at least in the case of this tutorial project, we wanted to go
|
|
through and clean up some of the generated names, as well as assign authorship
|
|
and project description etc. within the ``setup.py`` file. (Then commit those
|
|
changes and do another push, so we again have "clean" git status.)
|