Info |
---|
Notice that this page has been deprecated in favor of the new PyDM Tutorial in the SRF space |
Table of Contents |
---|
Git
Git is a command line version control tool that we use in development so that multiple people can work on one file at a time without stomping all over each other's changes. I would strongly recommend reading though the quick git intro I used in college before continuing down this page; I found it really helpful when I was first learning, and it'll help provide a lot of context for what comes next.
The Ubuntu command line tutorial could also be of interest if you're not familiar with using the command line interface.
Info | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
If you don't have internet, this is a dump of the resources taken on 6/26/20
|
...
PyDM
PyDM is next generation EDM! EDM is, unfortunately, the program used to make the typical LCLS home panel (the display with buttons and read backs and things).PyDM is basically a combination of EDM and PyQt (if you don't know what PyQt is, it's what we use to make Python GUIs). The goal is to eventually migrate all existing Python GUIs to PyDM, and to make any new ones going forward in PyDM, all while version controlling them using git and GitHub. The following tutorial will walk you through making a change to an existing PyDM panel and going through the review process to release it into production.
...
Tutorial
We're gonna get our feet wet with PyDM by adding your own personal Dev Panel to the production Operations Dev Panel!
- Set Up GitHub
- Create a personal copy of the production software
- Make sure you're either in the freshly copied repo in lcls-srv01 or mcclogin (step two left us in rhel6-64 if you're taking that route, so just ssh over to mcclogin)
- If on mcclogin, make sure to type "bash" and then "source /afs/slac/g/lcls/tools/script/UENVS.bash"
- If on mcclogin, make sure to type "bash" and then "source /afs/slac/g/lcls/tools/script/UENVS.bash"
Git
Local
GitHub
SLAC has a GitHub organization called SLAC Lab. Access to it isn't granted automatically, but it's pretty easy to get! Make a GitHub account (or use one that you already have) and send your username to Brian Van Klaveren (email bvan@slac.stanford.edu or ping brianv on Slack) asking for access. Note: This step has very high potential to end up out of date if someone else ends up managing SLAC Lab, so keep that in mind.
Production repositories locally live in ~/opsTools, and remotely live on GitHub.
PyDM
Tutorial
- Go to https://github.com/slaclab/devPanel
- Click "Fork" in the upper right corner
- Click the link that says [Your User Name]/devPanel (Mine says that I've already forked it, but yours should ask you where you want to fork it)
- Click the green "Clone or Download" button and copy the ssh path. If you see what looks like a URL, click the blue "Use SSH" link right above it
- Back on an OPI (or ssh'ed in), type "set_profile [Your Username]". This should take you to your personal physics directory. Make a new devPanel subdirectory
- In that subdirectory, run "git init"
- Still in that subdirectory, type "~/mgibbs/link_repo_to_github/link_repo_to_github.sh -i" and follow the prompts (if you don't feel like thinking about the AFS repo, you can use this default, but you should paste in the GitHub ssh link you got in Step 4 for your fork or you'll connect to mine! You'll get slightly different messages since I've already run this before)
- Type "git pull origin master" and type in your password when prompted (again, messages will be slightly different since I've done this before)
- Type "source use_pydm.sh"
- Type "mkdir [Your Name]" and head into that directory
- Type "designer &"
- Sometimes you get an error saying something about backup files. Ignore it(: In the program window that openspops up, click "Widget" and then "Create"
- In the Widget box on the left, scroll all the way down and drag a drop a PyDMShellCommand somewhere in the widget that popped up in the last step
- Right click anywhere in the widget that isn't the tiny shell command button, hover over "layout" at the bottom, and click "lay out in a grid"
- In the Object Inspector in the top right, rename that button something more descriptive by double clicking it, typing the new name, and pressing enter enter
- Right click the button itself and click "Change text..."
- Rename it something more descriptive and press enter enter
- In the property/value table in the middle leftright, scroll all the way down to "commands," double click the value box (it'll be blank at first, and then it'll be a button that says "Change String List"), Click "New", type "echo hello world!pydm ~/opsTools/devPanel/example/example.py", then click "OK"
- . This will launch the production example panel!
- Save this file as devPanel[Your Name].ui
- From here, open opsDevPanel.ui from the parent directory (~/[your username]/devPanel)
- Drag and drop a PyDMRelatedDisplayButton onto the newly opened devPanel.ui
- Right click rename the button itself and its object name like before
- Add the path to your personal dev panel in your subdirectory and save
- Back in your terminal in the devPanel directory, run "pydm opsDevPanel.ui" and you should see your creation! Feel free to play with it until it looks good to you!
- Run "git status" to see what's changed. It should be opsDevPanel.ui and a new folder with your name
- Run "git add [YOUR NEW FOLDER]" and "git add opsDevPanel.ui", then run another git status. They should both be staged for commit
- Run git commit -m "adding [YOUR NAME]'s dev panel"
- Push those changes to Github
- If on lcls-srv01, run "git push origin main" and log in when prompted
- If on mcclogin, ssh to rhel6-64, re-navigate to the repo, and run "git push origin main"
- If on lcls-srv01, run "git push origin main" and log in when prompted
- Back on your fork on GitHub, click "Pull Request"
- Click "Create Pull Request"
- Add slaclab/ops as a reviewer (by clicking on the gear and then searching), and then click "Create pull request"
- An admin will look at it to make sure that nothing important got deleted, and if they approve it, they'll merge it into production!
...
Afterword: Updating Your Personal Repo
Note that the tutorial didn't say anything about updating your personal copy if the production copy gets updated by someone else. There are two ways to do this, and it's really your choice which one to do.
...
GitHub Method
- In the SLAC Lab production repo, click "Pull Request" and then "New Pull Request"
- Click on "Compare across forks" and then pick your fork in the left hand drop down menu
- Click "create pull request", which will take you to the same page we had in the tutorial! The only difference here is that you don't need any reviewers because you're merging it into your personal fork.
You can just immediately merge it in on the next page by clicking "merge pull request"
Info Sometimes it'll say that it can't be merged automatically. This usually happens when you've edited the same file as one that got updated in production. One way to avoid this problem on GitHub is to always keep your fork's main up to date with production and do all your work in a different branch and just deal with the merge conflicts locally
- Using the steps in the tutorial, ssh into rhel6-64 and navigate to the repository you created with Matt's script and run "git --bare fetch origin main:main". Mine doesn't have output because it's already up to date, but yours should
- Back in your physics devPanel directory, run "git pull origin main", and that should be it! Again, your output will be different from mine because mine is already up to date.
...
Command Line Method
Info |
---|
This will rely heavily on git remotes. If you'd like to learn more about them, check this out! |
Pulling From the Local Production Copy
Assuming that you trust the custodian of the local production copy to keep it up to date, this method is probably the easiest.
In your physics devPanel directory, run "git remote add upstream ~/opsTools/devPanel"
- Now you can just run "git pull upstream main" whenever you'd like to bring your local copy up to date with production!
...
Pulling from the SLAC Lab Production Copy
If you don't trust the custodian of the local production copy to keep it up to date, then you can connect your bare AFS repo directly to SLAC Lab's production repo.
- Using the steps in the tutorial, ssh into rhel6-64, navigate to the bare repo you created with Matt's script, and run "git remote add upstream git@github.com:slaclab/devPanel.git" (gotten from the SLAC Lab devPanel page, much like we got it for our personal forks in the tutorial)
- Now, similar to in the GitHub method, you should run "git --bare fetch upstream main:main" (yes, I have an error message, but it's for stupid reasons. Yours should be fine)
- And now it's the same step as in the GitHub method, running "git pull origin main" from your devPanel physics directory.
Steps 2 and 3 will need to be run every time you want to update.
...
Next Steps
If you're interested in continuing with Python development in Operations (and I hope you are!), here are a couple things you could tackle as intro projects
Making a simple PyDM GUI
Probably the best place to start. If you look at opsDevPanel.ui (run "pydm opsDevPanel.ui"), you should see an "Example Dev Panel" button on it. If you click it, you'll launch a really simple GUI whose entire function is to print what it's doing. If you look in the example subdirectory, you'll see example.ui and example.py, which together make up that simple GUI. I created example.ui using designer in the exact same way we created our dev panels in the tutorial. The difference here is that the button on opsDevPanel.ui is a related display button that leads to a python file instead of a ui file (example/example.py – you can open it up in designer to see). If you look at example.py, you'll see the format for a PyDM GUI:
- Blue: The name of your GUI (and file – whatever name you choose for your GUI, the python file should be [name].py)
Green: The names you gave the UI elements in designer. Note that PyQt is an actual thing out in the google-able world; I literally googled "pyqt button pressed" to try to figure out how to get the "someone clicked this button" signal and connect it to something
- Red: The custom functions for that GUI! It can be anything you want, this is just an example of a GUI that prints out what you're doing, but you could make a GUI that calculates power or something
Anything not in a box is boilerplate and should be present in any PyDM GUI. There's also very helpful PyDM documentation that Matt and Hugo wrote if you really wanna dig into what all those other PyDM widgets you see in designer can do.
Info | ||
---|---|---|
| ||
If you're not familiar with Python and/or Object Oriented Programming, here's a nice guide I found that can help answer questions like "what is __init__?" |
Converting an existing Qt4 Python GUI to PyDM
This should theoretically be straightforward (famous last words). It should largely be taking a Qt4 GUI, deleting its autogenerated *_UI.py file, and changing Qt4 syntax to Qt5 syntax.
Migrating an existing Python GUI to ~/opsTools and version controlling it using git/GitHub
Most current GUIs live in /usr/local/lcls/tools/python/toolbox, which is both impossible to find and massively bloated with garbage files. Not only that, but they're also version controlled with CVS, which is a much less robust version control system (it allows you to overwrite someone else's changes if you don't know someone else is working on it...)
Migrating them should really just be moving the files to ~/opsTools, creating a SLAC Lab repository for it, connecting it using Matt's script, and updating references to it (like in buttons and launchpad)