.. 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.)