Welcome to ECE 651!
Welcome to ECE 651, where you will be writing a lot of Java this semester. Fundamentally, you will need a few things to do your Java development:
- A Unix-based OS (Linux, Mac OSX, or Windows Subsystem for Linux)
- To setup your Duke GitLab account, including an SSH key
- JDK (Java Development Kit) version 17 and Gradle version 7.3.3 recommended (higher might work, but we haven't tested)
- An editor: Emacs version 27 or higher is highly recommended.
The option we best support is Emacs on Ubnutu 22. You are welcome to use other options, but we want to provide a few words of caution for students opt for other editors
- We have historically found that students who don't use Emacs either do not learn how to make their editor work well for them and/or their editor just does not have the feature set that Emacs has. Watching students painfully and slowly write out code without the help of powerful editor features is incredibly frustrating.
- If your editor uses a non-standard build system, and the only way to build your code is to click a button in your editor, it will cause you problems when you need to automate your builds and tests in CI/CD. It may also cause problems working in a group with people who use other editors. Please be sure you can build your code with gradle
- It is possible to install JDK directly on Windows (outside WSL), but is completely unsupported by the course: do not expect the TAs or Professor to be able to help you if something is wrong.
- Most students who use other editors struggle to integrate test coverage with their editor. If your editor does not support code coverage integration, we will show you how to get an HTML report and view it in your web browser, but to me, this is no substitute for having the coverage shown right in your editor.
With that said, we are going to break this down into 5 sections, as described above
1: A Unix-based OS
We support the following options for a Unix-based OS to work on:
- A VCM server with Ubuntu 22 already installed. You can access this with FastX, a graphical desktop
- Work directly on your Mac
- Work in WSL on your Windows computer
- Install Virtual Box to give you a VM on your computer, and work in that.
We think that option 1 is easiest, but it is also the newest option (first available in Spring 2024).
Unix option 1: VCM server with FastX
- First, go to https://vcm.duke.edu/ and click "Reserve a VM" .
- On the list of VM options to reserve, there should be one specifically for ECE 651, choose that one.
- Accept the Terms of use
You should be on a screen that shows your VM information, including something like this:
Hostname: vcm-37657.vm.duke.edu
Operating System: ubuntu-22
Base memory: 4 GB
Processors: 2
VM Status: reserving
You will need the hostname to login to it. Also, the VM status of "reserving" means that it is not yet available. You can download FastX while you wait, but won't be able to login until the status changes to "complete" (you should get an email when this happens). It generally takes about 5 minutes, but may take longer when many reservations are being made at the start of the semester.
- While you wait, go to https://software.duke.edu/node/84
- You will need to login with your NetId. Sometimes when I login, I get an error. I just go to the URL bar of my browser and hit Enter to reload the page and it usually works (don't ask me why...)
- You should end up on a page for FastX, with an "Add To Cart" button in the middle of the page (note the price should be $0.00, so you don't actually have to pay anything). Next, hit the Checkout button. Most of the chekout page should be prefilled (if not, fill it in). Note that you need to choose University in the radio button at the bottom. Once you are done, hit "continue to next step", review the information, then hit continue again. You should end up on a page that says Checkout is Complete and directs you to where to view your orders.
- Follow the link to view your orders (or use the My Orders button at the top). The one you just did should be at the top. Click Download/License information and follow the instructions on that page.
- At this point, your VM should hopefully be setup. If not, you'll need to wait until it is ready.
- Open the FastX client on your computer. There should be a + (plus) button in the upper left to setup a new server. Press that. fill in the hostname with YOUR vcm's hostname. It should be something like vcm-37657.vm.duke.edu (but a different number, from the Hostname discussed above). Put your netid in the username box. Then press OK.
- You should now be back in the main window with an entry for that host. Double click that entry. You will probably get a warning about a webserver not running---that is fine. You should get a window that looks mostly empty but has a + (plus) button in the top left. Click on that and you should get a window with "Global Applications" and three choices: Default Desktop, Gnome, and XCFE. Choose "Default Desktop" and you should get a window that is a remote desktop of this VCM server. Note that the icon bar at the bottom should have a black square with a white $_ in it. That is the icon for your terminal. Go ahead and open that (you can click it multiple times to get more than one terminal window)
- At this point, you are ready to go to JDK setup.
Unix option 2: Work directly on your Mac
If you have a Mac, the built-in Terminal program gives you a Unix terminal. You can just go to step 2, as our Mac setup script will install Homebrew for you if you don't already have it.
Note that one of the most common problems that Mac users have when trying to develop directly is having old versions of software available and getting them. E.g., if you have an ancient Gradle version (from say 2015) installed by default, you will run into problem.
We also can't really test this on a "fresh" setup without getting a new Mac, and can't test it on a setup exactly like your computer without installing exactly the same stuff you have (including the same OSX version). Accordingly, while we have tested this in the past, we don't retest it each year, so there is some chance that things that worked ok in the past don't work now.
Unix option 3: Work in WSL on your Windows computer
Follow these instructions
https://adhilton.pratt.duke.edu/development-setup-wsl
Unix option 4: Install Virtual Box
Follow the instructions of Section 1 of the old walkthrough. Be sure to download an Ubuntu 22 (or later) image to install.
2: Setup your Duke GitLab account
Go to https://gitlab.oit.duke.edu/ . You do NOT want to use the username and password box. Instead, go right under that and find the "Duke OAuth2" button. Click the Duke OAuth2 button which will take you to the Shibboleth login page for you to login with your NetId. Once you are logged in, you will want to setup an SSH key.
You can find directions for how to generate an SSH keypair here. You probably did this last semester in 551. You can use the same key if you want, but need to make sure the private key is available wherever you are developing (so if you are developing on a VCM machine, you would need to scp it to that machine). It is probably easier to just generate a new keypair wherever you are. Note that you do not need to upload it to OIT's publickey management infrastructure.
Instead, you should upload the public key to GitLab as follows. First, look in the upper left of the page that you ended up on after logging into Gitlab. There should be a fox icon in the top left, with a few more buttons to the right. One of those should be your profile icon. If you click on that, you should get a menu including "Edit Profile". Click "Edit Profile". Now find "SSH Keys" in the menu on the left and click that. Find the "Add New Key" button on the upper right side of the page and click it. Paste in your PUBLIC key, and fill in the title (it can be whatever you want, but descriptive is good, e.g. : 651 development key). Then click "Add Key".
3: Install JDK and Gradle
We've made some scripts that should install JDK and Gradle for you.
The easiest way to get the scripts is by cloning a git repository, but that means you need to have git installed.
If you are on Mac (meaning working directly on a Mac, not on a Mac using a virtual machine that is Linux), and do not already have the command line tools, run
sudo xcode-select --install
type your password, and accept the agreement.
If you are on Linux (including WSL), run
sudo apt install git
Once you have done that, run (note: if you are in Linux, paste is middle-click. If you have a two button mouse, you can click both left and right at the same time to paste. If you have a no-buttons track pad [e.g., Mac laptop without an external mouse], we'll show you how to bind paste to a key in a moment...)
git clone git@gitlab.oit.duke.edu:adh39/ece651-dev-setup.git
Now you should be able to
cd ece651-dev-setup
If you are on Mac (again, directly on a Mac), run
./packages-mac.sh
If you are on Linux, run
./packages-linux.sh
Now, if you dont have the ability to middle click to paste, you can run
./mac-paste.sh
This will rebind your right option key to be middle click. You can now paste with that key.
4: An Editor (Emacs)
If you are using Emacs, you should be able to just run
./emacs-config.sh
and it will install a bunch of packages and set you up for some good Java editing features.
If you are using VIM, you are on your own in setting things up.
If you are using some other editor, please be sure that you have all of the following capabilities:
Your editor works with any programming language. Using a different editor for every language is miserable and inefficient.
You can build with gradle. Some editors only work with their own non-standard build systems.
Your editor has (or you can setup) a keybind to switch between implementation code and the corresponding JUnit test file. You should be doing this A LOT and if you are spending a lto of time searching through menus and file navigation dialogs, it really slows you down.
You have autocomplete, syntax highlighting, and something analogous to flycheck (where it shows you errors as you code)
You can do most of your major development tasks from the keyboard. If you do it more than once a day, you should have a keybind for it and not need to go searching through menus to find it.
That's the absolute minimum set of features. We would strongly recommend test coverage integration with clover (showing test coverage in editor), keyboard macros, and debugger integration. Git integration is wonderful too---Emacs has great Git (and Gitlab) integration.
If your editor is lacking in the above features we'd recommend investing some time in Emacs.
Editor Practice/Skills
Whatever editor you are using, we recommend you spend a bit of time familiarizing yoruself with it in a Gradle/Java setup. Our old walkthrough has a tutorial on Gradle project setup (Section 4), and Emacs (Seciton 5). We recommend you do both---even if you are using a different editor, you should still go through Section 5 and do the same things in your editor that we are describing in Emacs to make sure you know how to do them.