Skip to content

Commit

Permalink
README cleanup and language tweaks
Browse files Browse the repository at this point in the history
  • Loading branch information
@flavorjones
flavorjones committed Feb 27, 2015
1 parent be0d46f commit 571938a
Showing 1 changed file with 70 additions and 72 deletions.
142 changes: 70 additions & 72 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,59 +1,56 @@
# MiniPortile

![build status](https://travis-ci.org/flavorjones/mini_portile.svg?branch=master)
![travis status](https://travis-ci.org/flavorjones/mini_portile.svg?branch=master)

* [Source Code](https://github.com/flavorjones/mini_portile)
* [Bug Reports](https://github.com/flavorjones/mini_portile/issues)

This project is a minimalistic, simplistic and stupid implementation of a port/recipe
system **for developers**.
This project is a minimalistic implementation of a port/recipe system
**for developers**.

Because _"Works on my machine"_ is unacceptable for a library maintainer.

## Another port system, srsly?

No, `mini_portile` is not a general port system. It is not aimed to
take over apt, macports or anything like that.
## Not Another Package Management System

The rationale is simple.
`mini_portile` is not a general package management system. It is not
aimed to replace apt, macports or homebrew.

You create a library A that uses B at runtime or compile time. Target audience
of your library might have different versions of B installed than yours.
It's intended primarily to make sure that you, as the developer of a
library, can reproduce a user's dependencies and environment by
specifying a specific version of an underlying dependency that you'd
like to use.

You know, _"Works on my machine"_ is not what you expect from one
developer to another.
So, if a user says, "This bug happens on my system that uses libiconv
1.13.1", `mini_portile` should make it easy for you to download,
compile and link against libiconv 1.13.1; and run your test suite
against it.

Developers having problems report them back to you, and what you do then?
Compile B locally, replacing your existing installation of B or simply hacking
things around so nothing breaks.

All this, manually.

Computers are tools, are meant to help us, not the other way around.

What if I tell you the above scenario can be simplified with something like
this:
This scenario might be simplified with something like this:

```
rake compile B_VERSION=1.2.3
rake compile LIBICONV_VERSION=1.13.1
```

And your library will use the version of B you specified. Done.
(For your homework, you can make libiconv version be taken from the
appropriate `ENV` variables.)



## You make it sound easy, where is the catch?
## Sounds easy, but where's the catch?

You got me, there is a catch. At this time (and highly likely will be
always) `MiniPortile` is only compatible with GCC compilers and
autoconf/configure-based projects.
always) `MiniPortile` is only compatible with **GCC compilers** and
**autoconf**- or **configure**-based projects.

It assumes the library you want to build contains a `configure`
script, which all the autoconf-based libraries do.
That is, it assumes the library you want to build contains a
`configure` script, which all the autoconf-based libraries do.


### How to use

Now that you know the catch, and you're still reading this, let me
show you a quick example:
Now that you know the catch, and you're still reading this, here is a
quick example:

```ruby
require "mini_portile"
Expand All @@ -69,43 +66,45 @@ GCC will find this library and prefer it over a system-wide
installation.


### Structure
### Directory Structure Conventions

`MiniPortile` follows the principle of **convention over configuration** and
established a folder structure where is going to place files and perform work.

Take the above example, and let's draw some picture:

```
mylib
|-- ports
| |-- archives
| | `-- libiconv-1.13.1.tar.gz
| `-- <platform>
| `-- libiconv
| `-- 1.13.1
| |-- bin
| |-- include
| `-- lib
`-- tmp
`-- <platform>
`-- ports
mylib
|-- ports
| |-- archives
| | `-- libiconv-1.13.1.tar.gz
| `-- <platform>
| `-- libiconv
| `-- 1.13.1
| |-- bin
| |-- include
| `-- lib
`-- tmp
`-- <platform>
`-- ports
```

In above structure, `platform` refers to the architecture that represents
the operating system you're using (e.g. i686-linux, i386-mingw32, etc).
In above structure, `<platform>` refers to the architecture that
represents the operating system you're using (e.g. i686-linux,
i386-mingw32, etc).

Inside this folder, `MiniPortile` will store the artifacts that result from the
compilation process. As you can see, it versions out the library so you can
run multiple version combination without compromising these overlap each other.
Inside the platform folder, `MiniPortile` will store the artifacts
that result from the compilation process. The library is versioned so
you can keep multiple versions around on disk without clobbering
anything.

`archives` is where downloaded source files are stored. It is recommended
you avoid trashing that folder so no further downloads will be required (save
bandwidth, save the world).
`archives` is where downloaded source files are cached. It is
recommended you avoid trashing that folder to avoid downloading the
same file multiple times (save bandwidth, save the world).

`tmp` is where compilation is performed and can be safely discarded.

Use the recipe's `path` to obtain the full path to the installation
Use the recipe's `#path` to obtain the full path to the installation
directory:

```ruby
Expand All @@ -115,12 +114,10 @@ recipe.path # => /home/luis/projects/myapp/ports/i686-linux/libiconv/1.13.1

### How can I combine this with my compilation task?

In the simplified proposal, the idea is that using Rake, your
`compile` task depends on `MiniPortile` compilation and most important,
activation.
In the simplest case, your rake `compile` task will depend on
`MiniPortile` compilation and most important, activation.

Take the following as a simplification of how you can use `MiniPortile` with
rake:
Example:

```ruby
task :libiconv do
Expand All @@ -137,28 +134,28 @@ task :libiconv do
end

task :compile => [:libiconv] do
# ...
# ... your library's compilation task ...
end
```

The above example will:

* Compile the library only once (using a timestamp file)
* Ensure compiled library gets activated every time
* Make compile task depend on compiled library activation
* **compile** the library only once (using a timestamp file)
* ensure compiled library is **activated**
* make the compile task depend upon compiled library activation

For your homework, you can make libiconv version be taken from `ENV`
variables or a configuration file.
As an exercise for the reader, you could specify the libiconv version
in an environment variable or a configuration file.


### Native or cross-compilation
### Native and/or Cross Compilation

The above example covers the normal use case: compile support
libraries natively.
The above example covers the normal use case: compiling dependencies
natively.

`MiniPortile` also covers another use case, which is the
cross-compilation of the support libraries to be used as part of a
binary gem compilation.
cross-compilation of the dependencies to be used as part of a binary
gem compilation.

It is the perfect complementary tool for
[`rake-compiler`](https://github.com/rake-compiler/rake-compiler) and
Expand All @@ -170,10 +167,11 @@ Depending on your usage of `rake-compiler`, you will need to use
Please refer to the examples directory for simplified and practical usage.


### Supported scenarios
### Supported Scenarios

As mentioned before, MiniPortile requires a GCC compiler toolchain. This has
been tested against Ubuntu, OSX and even Windows (RubyInstaller with DevKit)
As mentioned before, `MiniPortile` requires a GCC compiler
toolchain. This has been tested against Ubuntu, OSX and even Windows
(RubyInstaller with DevKit)


## License
Expand Down

0 comments on commit 571938a

Please sign in to comment.