Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/PistonDevelopers/rust-empty

A Makefile to get started with Rust (DEPRECATED)
https://github.com/PistonDevelopers/rust-empty

Last synced: about 22 hours ago
JSON representation

A Makefile to get started with Rust (DEPRECATED)

Awesome Lists containing this project

README 

        
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](https://github.com/rust-lang/cargo)  

Cargo will replace a subset of the features of Rust-Empty over time.  



##Example 1: Hello World



1. Copy [Makefile](https://raw.githubusercontent.com/bvssvni/rust-empty/master/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.

3. `git clone `

4. Copy `Makefile` to the folder.

5. `make git-ignore`

6. `make lib`

7. 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  `, 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  ` 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