UPE may have experimental features, that aren’t finished or tested enough to be on the main software. The documentation for this features can be found on the latest version of documentation. To view it, click on the v:master (bottom of the sidebar) and versions ‣ latest.
There you will see the standard documentation and some new pages. These pages should start with this:
Experimental
This feature is experimental and shouldn’t be used on a production environment.
Branch: exp
(In this case, exp is the branch used, but can be any other name.)
To test this feature, you’ll need:
Any other software, if indicated on the documentation.
Hint
You’ll have to use the terminal. To try if it works, open one (Applications ‣ Utilities ‣ Terminal on Mac and Terminal or Konsole on Linux) and write:
echo "I'll use UPE's experimental features"
It should return:
I'll use UPE's experimental features
Some useful commands:
# A comment. It'll be ignored
cd # Go to your home dir
DIR=~ # Sets DIR to ~ (your home dir). Now, $DIR will be ~
cd $DIR # Go to $DIR ($ indicates a variable)
pwd # Shows where you are (Present Working Dir)
ls # Lists the contents of the current dir
ls $DIR # Lists the contents of $DIR
echo $DIR # Return $DIR (it can be anything)
exit # Close the terminal
Uninstall UPE if you have it installed:
sudo pip uninstall upe
You’ll be asked for your password (you won’t see what you are typing) and Pip will ask you:
Uninstalling UPE:
<list of files>
Proceed (y/n)?
Answer y.
Download UPE’s source code with Git (and enter to its directory):
git clone https://www.bitbucket.org/universalpackageeditor/upe.git
cd upe
Download the experimental branch:
Git has branches where new, unstable features are added and tested before being included (merged) on the master branch (the main branch). The experimental features are in one of these branches. Do you remember the Experimental warning? Look for the last line which says something like:
Branch: <branch>
We will assume that <branch> is exp:
branch=exp # Remember to change the branch!
git fetch
git checkout $branch
git pull -u origin $branch # This is optional, but it'll make upgrading easier.
Installing UPE with the feature:
Usually, you would use Pip to install UPE, but the PyPI (which provides the downloads to Pip) only contains the stable (master) version, so you have to use the alternative method:
sudo pip install .
Note
Watch out the final .!
Run UPE normally:
From a Python console:
>>> import upe
>>> from upe import *
Warning
The feature may not work or may even break the other UPE modules. If so, make sure that the bug isn’t in “Known bugs” (if any) and sumbit a bug report. Make sure to select the right component.
Important
Don’t delete the directory where you downloded the source (i.e. from where you ran pip), as it’ll be needed when upgrading.
Hint
You’ll have to use Windows’ console (CMD). To try if it works, open one (Start ‣ Command line or Control-R and cmd.exe) and write:
ECHO "I'll use UPE's experimental features"
It should return:
I'll use UPE's experimental features
Some useful commands:
REM A comment. It'll be ignored
:: Also represents a comment.
SET DIR=~
REM SET is used to create a variable. Now, %DIR% will be ~ (your user directory)
DIR
REM Lists the contents of the current dir
DIR %DIR%
REM Lists the contents of %DIR%
CD %DIR%
REM Go to %DIR%
ECHO %DIR%
REM Returns %DIR% (It can be anything)
EXIT
:: Closes the windows
Tip
On Windows, commands are case-insensitive. Also, .EXE is not required, but may be used if the command without the .EXE doesn’t work.
Note
We assume that both Python (and Pip) and Git are on the %PATH%.
Uninstall UPE (if installed)
PIP uninstall upe
Pip will ask you:
Uninstalling UPE:
<list of files>
Proceed (y/n)?
Answer y.
Warning
Pip (and Python) uses the Unix standard (like Linux and Mac), so it’s case-sensitive (but not the name, which is handled by CMD.EXE, not by Pip).
Download UPE’s source code with Git (and enter to its directory):
GIT clone https://www.bitbucket.org/universalpackageeditor/upe.git
CD upe
Warning
Git also uses the Unix standard.
Download the experimental branch:
Git has branches where new, unstable features are added and tested before being included (merged) on the master branch (the main branch). The experimental features are in one of these branches. Do you remember the Experimental warning? Look for the last line which says something like:
Branch: <branch>
We will assume that <branch> is exp:
SET branch=exp
REM Remember to change the branch!
GIT fetch
GIT checkout %branch%
GIT pull -u origin %branch%
REM This last line is optional, but it'll make upgrading easier.
Installing UPE with the feature:
Usually, you would use Pip to install UPE, but the PyPI (which provides the downloads to Pip) only contains the stable (master) version, so you have to use the alternative method:
As Administrator
You have to run the following code as administrator (Start ‣ Command prompt ‣ Right-click ‣ [UAC] Run as administrator).
PIP install .
Run UPE normally:
From a Python console:
>>> import upe
>>> from upe import *
Warning
The feature may not work or may even break the other UPE modules. If so, make sure that the bug isn’t in “Known bugs” (if any) and sumbit a bug report. Make sure to select the right component.
Important
Don’t delete the directory where you downloded the source (i.e. from where you ran setup.py), as it’ll be needed when upgrading.
Note
As the software you installed is not stable (that’s why it’s separed from the main branch), it’s recommended that you upgrade before using it (once per day). It may not download anything (‘Already up-to-date’), but there may be changes. If you don’t upgrade before using it, you mustn’t sumbit bug reports until you update.
As you are using a non-standard version, you can’t upgrade using Pip, you have to do it manually:
Open a terminal (CMD.EXE on Windows) and cd to the directory where you downloaded the source and write:
Linux and Mac:
git pull python setup.py build # Remember to add python3 if neccessary sudo python setup.py install # Idem
Windows:
GIT pullAs Administrator
Run this as administrator:
PIP install .
Note
If you haven’t run the last line when installing, run it now (only the first time you upgrade):
Linux and Mac:
git pull -u origin $branch # Change $branch for your branch.
Windows:
GIT pull -u origin %branch%
REM Change %branch% for your branch.
You may want to return to the main (master) branch because:
This case it’s the longest, but it ensures that no data is lost:
Do a final upgrade:
git pull
sudo pip install .
Enter the following code:
branch=exp # Change 'exp' for the appropiate branch
git checkout master
git pull origin master
git branch -d $branch
# If you see an error, it means that the branch isn't still merged, so run:
git checkout $branch
exit
# If it's fully merged:
sudo pip uninstall -y upe
sudo pip install upe
Important
Only run the git checkout $branch if you saw an error. By running it, everything will return to the experimental state.
If everything went OK, delete the directory where the source was:
cd .. # Go to the upper dir rm -r upe/ # Assuming the source was in 'upe'
Now you can use this command to upgrade UPE:
sudo pip install --upgrade upe
Note
Commands with a ! have to be run as Administrator.
Do a final upgrade:
GIT pull
PY setup.py build
! PIP install .
Enter the following code:
SET branch=exp
REM Change 'exp' for the appropiate branch
GIT checkout master
GIT pull origin master
GIT branch -d %branch%
REM If you see an error, it means that the branch isn't still merged, so run:
GIT checkout %branch%
EXIT
REM If it's fully merged:
! PIP uninstall upe
! PIP install upe
Important
Only run the GIT checkout %branch% if you saw an error. By running it, everything will return to the experimental state.
If everything went OK, delete the directory where the source was:
CD ..
REM Go to the upper dir.
REM Assuming the source was in 'upe':
DEL upe
:: Yes, you are sure
Note
These commands are run from the source directory.
Linux and Mac:
sudo pip uninstall upe cd .. # Assuming the source directory is 'upe': rm -r upe/ sudo pip install upe # To install it again (stable)
Windows (run as Administrator):
PIP uninstall upe CD .. REM Assuming the source directory is 'upe': DEL upe REM To install it again (stable): PIP install upe