Rust-Empty

Notice: Rust-Empty is deprecated and replaced by Cargo, which comes with Rust

A Makefile to get started with Rust development.
MIT license (or just use it as you like).
Requires Linux or Mac OS X (with developer tools).
Experimental support for Mingw on Windows.

If you want to contact me, I often hang around in the #rust IRC channel (bvssvni)

It is recommended to install Cargo
Cargo will replace a subset of the features of Rust-Empty over time.

##Example 1: Hello World

1. Copy Makefile to a new empty project folder.
2. Open the Terminal and navigate to the project folder.
3. make nightly-install
4. make run to create and run "hello world"

The "hello world" example is created when there is no src/main.rs.

##Example 2: New open source library

1. Create new repository on Github.
2. git clone <url>
3. Copy Makefile to the folder.
4. make git-ignore
5. make lib
6. Change DEFAULT = help to DEFAULT = lib

##Example 3: Compile library on file changes

1. Assuming you have set up the library and set the DEFAULT parameter properly
2. make watch to generate the watch script
3. ./watch.sh
4. Edit the source and save to do compilation

##Example 4: Compile and run application on file changes

1. Assuming you have set up the application properly
2. make watch to generate the watch script
3. ./watch.sh src "make run"
4. Edit the source and save to compile and run the application

This technique can be applied to running unit tests and benchmarks as well. To chain commands, use the && operator, for example ./watch.sh src "make test-internal && bench-internal".

##Example 5: Compile example with conditional compilation

1. Assume you have an example 'examples/hello.rs'
2. Put #[cfg(foo)] in 'hello.rs' where you want want conditional compilation
3. Type make examples/hello.rs COMPILER_FLAGS+="--cfg foo"

The 'foo' part can be switched with any other flag.
You can also have multiple flags and require more than one by using #[cfg(foo, bar)]. Type make examples/hello.rs COMPILER_FLAGS+="--cfg foo --cfg bar" to activate both.

##What is Rust-Empty?

Rust-Empty is a user friendly Makefile/Bash setup tool for Rust programmers.
It automates setup of directories and configuration files.
Once setup is completed, replace or modify the Makefile to suit your needs.
The Makefile works out of the box on Linux and OSX (with developer tools).
The setup uses best practices and conventions learned from the Rust community.
Pull requests/fixes are welcome!

Latest feature: Build symlink dependencies!

What are these 'best practices'?

For example:

• Put code in a src/ directory
• Add a crate_id attribute for your library
• Deny missing doc attribute for library
• A .gitignore to keep repository clean
• Library dependencies should be in target/deps directory
• Example programs better not be in the src/ directory
• Need a -O flag to compile optimized code
• Dependencies, rust-nightly check through Travis CI etc.

###Goals

• Work on Linux, Mac OS X and Mingw on Windows
• Convention by 'best practice' of Rust community
• Features are optional, non-interfering and gives informative output
• Integrate with other tools from Rust community

###Non-Goals

• Replace Cargo, the Rust package manager
• Backward compatibility
• Require any sort of internal configuration

##Usage

1. Create a new empty folder for your project.
2. Copy 'Makefile' to the project folder.
3. Open the Terminal window and navigate to the project folder.
4. Type 'make help'.

--- rust-empty (0.7 000)
make run               - Runs executable
make exe               - Builds main executable
make lib               - Both static and dynamic library
make rlib              - Static library
make dylib             - Dynamic library
make test              - Tests library internally and externally
make test-internal     - Tests library internally
make test-external     - Tests library externally
make bench             - Benchmarks library internally and externally
make bench-internal    - Benchmarks library internally
make bench-external    - Benchmarks library externally
make doc               - Builds documentation for library
make git-ignore        - Setup files to be ignored by Git
make examples          - Builds examples
make cargo-exe         - Setup executable package
make cargo-lib         - Setup library package
make rust-ci-lib       - Setup Travis CI Rust library
make rust-ci-exe       - Setup Travis CI Rust executable
make rusti             - Setup 'rusti.sh' for interactive Rust
make watch             - Setup 'watch.sh' for compilation on save
make loc               - Count lines of code in src folder
make nightly-install   - Installs Rust nightly build
make nightly-uninstall - Uninstalls Rust nightly build
make clean             - Deletes binaries and documentation.
make clear-project     - WARNING: Deletes project files except 'Makefile'
make clear-git         - WARNING: Deletes Git setup
make symlink-build     - Creates a script for building dependencies
make symlink-info      - Symlinked libraries dependency info
make target-dir        - Creates directory for current target

All the commands creates the files and folders necessary to compile.
For example, if you type make exe it will add a hello-world program to src/main.rs.
You can use make clear-project to revert back to just the 'Makefile'.

##Unit Testing & Benchmarking

Internal unit tests and benchmarks are located in the same source as the library, src/lib.rs.
External unit tests and benchmarks are located in src/test.rs.

##Linking to Libraries

The directory target/deps/ is linked by default. If you put Rust libraries in this directory it will link statically if there is an ".rlib" file or dynamically if ".dylib" (OSX), ".so" (Linux) or ".dll" (Window).

##Symlinked Libraries

A symlink is a file that points to another file. Symlinks are useful when working across multiple repositories and testing integration.

Using the command ln -s <from> <to>, you can link the output file from another project to the target/deps/ folder.

The command make symlink-info creates a file .symlink-info that contains the file name, current commit, the remote origin url and which remote branches this commit is available. For more information about how to read '.symlink-info' files, see https://github.com/bvssvni/rust-empty/issues/114

NOTICE: The ln -s <from> <to> for relative file names does not work on OSX. Use absolute file names instead. For example ln -s /Users/myser/Desktop/mylibrary/target/x86_64-apple-darwin/lib/mylib.rlib target/x86_64-apple-darwin/mylib.rlib. See https://github.com/bvssvni/rust-empty/issues/100

The command make symlink-build creates a file build.sh that can build projects by symlinks.
You can type ./build.sh to build just the project, or ./build.sh deps to build everything.

##Introduction To Rust

Rust is a programming language developed at Mozilla Research.

Rust nightly builds
Rust at wikipedia
Official web page
Documentation at Github wiki
Rust at Reddit
Rust IRC channel
Editor syntax highlighting
Rust packages

###For those new to terminal/Github:

How to use the terminal
How to use Vim
How to use Github

###Rust CI

Each night the latest version of Rust on Ubuntu is built against a list of projects.
Add project by following instructions on the site:

Rust CI