Skip to content

Getting Started with Development

Jump to bottom Edit New page
John Warwick edited this page Sep 12, 2017 · 76 revisions

This page contains all the information you need to get started with developing as well as useful tips (see also this issue).

Language

The main language the whole project is written in is Clojure. Below are a few links to useful learning resources and documentation of Clojure and libraries used:

  • Clojure for the Brave and True - a nice online crash course of Clojure, written in accessible language
  • ClojureDocs - online Clojure documentation
  • Om - ClojureScript interface to Facebook's React. Used in many places on the web presentation side.
  • Hiccup and Ŝablono guides - they describe the HTML templating libraries used in the .cljs files.

IDE

There are several options available, including:

Dependencies

You need the following dependencies installed:

Here's a guide for Windows specifically

Git

If you want to contribute, you should fork the mtgred/netrunner repository on github.

After cloning your own fork on your machine, configure mtgred/netrunner as a remote.

$ git remote add upstream https://github.com/mtgred/netrunner.git

When you run git remote -v, you now should see something like this:

origin  https://github.com/yourgithubname/netrunner (fetch)
origin  https://github.com/yourgithubname/netrunner (push)
upstream        https://github.com/mtgred/netrunner.git (fetch)
upstream        https://github.com/mtgred/netrunner.git (push)

To keep your own repository up-to-date, refer to Syncing a fork.

If you want to start coding a feature or fix a bug, simply use

git checkout -b your_new_branch_name upstream/master

to create a local copy of the current master branch named your_new_branch_name that can easily be merged with a pull request.

Push it to your own repo with git push origin your_new_branch_name and create a pull request via the github website.

.gitignore

Adding IDE-specific files to .gitignore should happen in a global gitignore file, e.g. in ~/.gitignore:

# IDEA IntelliJ files
.idea
*.iml

And then inform git of this file via:

git config --global core.excludesfile '~/.gitignore'

Installation

Install Node.js dependencies:

$ npm install

npm install throws errors when trying to compile modules on Windows :-(

You have to specify the --msvs_version flag. So, if you use Visual Studio 2013, run

npm install --msvs_version=2013

I'm still getting errors like error: ‘NewSymbol’ is not a member of ‘v8::String’ when npm tries to compile gyp on Windows :-(

There's a problem with the engine.io node module that depends on an old version of the ws module. See this and this issue for more information.

npm install throws errors on MacOS that complain about zmq

To be able to install and find libzmq, first install Homebrew, then use it to install zeromq and pkg-config:

$ brew install zeromq
$ brew install pkg-config

npm install fails on Linux: npm WARN This failure might be due to the use of legacy binary "node"

Install the nodejs-legacy package:

sudo apt-get install nodejs-legacy

Install JavaScript dependencies:

$ bower install

Get Up and Running

1. Launch MongoDB (possibly with --dbpath option specifying card data directory) and fetch card data:

$ mongod
$ npm run fetch

This data fetch only needs to be performed if it's your first time building the project OR new card data has been made available on NetrunnerDB and you want to update your local data (e.g., a new data pack).

On Windows, run mongod.exe. See Install MongoDB on Windows.

If you get time-out errors (ETIMEDOUT) while running coffee fetch.coffee the data is still being downloaded if you see the card numbers being output in the terminal window. Just rerun the fetch.coffee until all cards are downloaded (no more numbers being printed).

2. [OPTIONAL] Compile and watch client side ClojureScript (only necessary if this is your first time building the project OR any .cljs files have been edited/modified and you need to update the UI):

$ lein cljsbuild auto dev

3. [OPTIONAL] Compile and watch CSS files (this step can be skipped if you have no plans to modify CSS/layout items):

$ stylus -w src/css -o resources/public/css/

4. Compile server side Clojure files

$ lein uberjar

5. Launch game server:

$ java -jar target/netrunner-0.1.0-SNAPSHOT-standalone.jar

6. Launch the Node server

$ npm run start

7. Run browser(s)

Open one or more browser sessions and visit: http://localhost:1042

Minimalist Alternative to Steps 4 and 5

Instead of building the production JAR files and running them with Java, a much faster way of launching the game server is to run the REPL (read-eval-print-loop) directly from the command line:

$ lein repl

This compiles the project if it's out of date, then launches an interactive shell from which you can type and evaluate Clojure commands. Inside the REPL, do (future-call dev) to launch the game server. Once you have a game initiated, you can modify card code and reload it with (load-file "src/clj/game/cards.clj") and very quickly see changes reflected in an ongoing game by simply trashing/discarding a copy of the card in question and reinstalling it or playing it again to see the new behavior.

Automated Environment

To get a local copy running with one command, see https://github.com/astrostl/nrdev

Setting up IntelliJ IDEA

How can I use a REPL while running the server?

Create a new Run Configuration and choose Clojure REPL -> Local:

Setting a REPL

When the REPL started, use (future-call dev) to start the game server.

Using IntelliJ IDEA with Cursive

I start a REPL from IntelliJ IDEA, but I get the following error: 'No nREPL ack received'.

Cursive uses a default time out of 60 seconds when trying to connect to the REPL. Change Settings -> Clojure -> REPL startup timeout to a higher value:

Increase the timeout

How can I access the code in the REPL?

Right click the file in the editor, REPL -> Switch REPL NS to current file or run (in-ns 'game.core) to switch the namespace

How do I run the tests?

Run lein test test.all from the command line.

I have the REPL up and running, now what?

You find the game state in @game-states. You probably want to run (def state (second (first @game-states))) as soon as you started your game so you can easily access its state now via @state.

So, I have changed a card, now what?

Run (load-file "src/clj/game/cards.clj") to reload all cards. Note that if the card you changed is already in play, you have to play it again before you see your code changes.

Using Emacs with Cider

If you want to use Emacs you have to install clojure-mode and cider. Cider allows you to connect Emacs to a REPL with C-c M-j. To reload a function, it's C-c C-c with the cursor inside the function definition. To reload a file (eg. card.clj) it's C-c C-k.

Videos

These live-coding videos may help you with some of the basics:

Slack channel

The main communication channel between developers, besides GitHub, is the team's Slack Channel. To request access, send an email to mtgred stating who you are on GitHub and linking two Pull Requests you got accepted into the repository.

Good Starting Issues

If you want to look for some of the easier issues to get started, look through our GitHub issues for issues labeled easy. These usually don't require in-depth codebase knowledge, and changes required to fix them shouldn't involve more than 1-3 source files.

Pull requests and branches

There are two main branches in this repository, master and dev. TODO

Continuous Integration

The project is configured to integrate with CircleCI. Create a CircleCI account and create a new project linked to your Github fork of this project. CircleCI will automatically build and run tests when you push changes to your repo.

The current configuration uses CircleCI v1.0. Configure your CircleCI project settings to use Ubuntu 12.04 (Precise) in Project Settings > Build Environment > OS to use for builds. If you fail to modify the default build OS, you will receive errors when attempting to stop mongodb.

Add a custom footer

Jinteki.net Guide

Dev Pages

Progress Reports

Clone this wiki locally