The following is a guide on how to use Buttress v0.5.1. If you have a question not answered here, please visit our forum and ask away!
What follows is a comprehensive guide to installing Buttress - skip sections if they do not apply to you.
Buttress is written in Java and you need the Java Virtual Machine to run it. If you use Azureus as your Bit Torrent client then you should have no problems.
If you're unsure about whether you have Java installed, then visit this page (opens in a new window) to run a test. If it says you have Java, you should be all set. If you don't, follow the instructions to get Java installed.
Once Java is on your machine, you need to download Buttress. The latest version at the time of writing is v0.5. When new versions are released, they will be available on the project page at SourceForge.net. This page also has older versions of Buttress for those interested.
(Note: Clicking a download link will take you to a page asking you to select a mirror - choose the server closest to you for best results)
Start by downloading and extracting the zip file to your desired directory ("C:\Program Files\Buttress" perhaps?). Then, double click the jar file ("Buttress.jar") and Buttress will begin to run; if that doesn't work, run Buttress by double clicking the Buttress executable ("Buttress.exe"). Jump ahead to how to use Buttress - there's some things you need to set up.
On non-Windows operating systems, you'll need to run Buttress from the .jar file. Assuming you have Java installed and the right things in your environment variables, this can be done at a command line with the command:
java -jar Buttress.jar
You can create a shell script to do this for you. By placing or linking to that script in a directory in your environment variable, you can run it with a simple
./scriptname
You can also create a shortcut on your desktop to peform this if you wish.
(Note: I'm no Linux guru so if there's a better way to do this, please get in touch! :)
Nearly there, just need to set a few things up - as described in the next section.
When running Buttress for the first time, you'll be presented with the Buttress license agreement (the GNU GPL, version 2), which you have to agree to to use the software. You'll then be taken to the Config menu where you get to set Buttress' main options.
First, there is a field marked "Delay between updates." This is in minutes and is initially set to 10. This means that every 10 minutes, Buttress will connect to the RSS feeds and check for new items on the feeds. You can change the delay to whatever you like (anything over 10 minutes... 14 minutes, 2562 minutes, whatever).
In order to work, Buttress needs to know where the Bit Torrent client is installed on your computer and also, where Buttress is installed. You will need to enter these details. Clicking on the button marked "Set BT Path" brings up a file manager which you can use to navigate to your Bit Torrent client. For example, if you were using Azureus which was installed in "C:\Program Files\Azureus\" you'd browse to that folder and open "Azureus.exe".
Now do the same for the folder that Buttress is installed in by clicking the button marked "Set Buttress Path". This is slightly different as you are not required to highlight any specific file - just navigate to the folder (i.e. "C:\Program Files\Buttress\") and click Open.
Next, you'll see the "Auto Start Bittorrent" checkbox. Turning this option on makes Buttress automatically start your Bit Torrent client whenever it finds a torrent you're interested in. Leaving this option off just makes Buttress download the torrent and move on with life.
Finally, there is the "Send Emails on Critical Errors" checkbox with the "Explanation" button next to it. Click the explanation button to have your explanation... We request that you do turn on this option so that we can know what's wrong in Buttress, but turning error emailing on is by no means required for you use or enjoyment of Buttress in any way, it just tells us what to fix in later versions.
Clicking on "OK" in the Config tab will store the settings so that you do not need to enter them every time you run Buttress.
PLEASE NOTE:
It is very important to make sure these settings are correct otherwise Bit Torrent downloads will not start!
It is worth testing your details by giving Buttress a feed (ie, "http://bt.etree.org/rss/bt_etree_org.rdf"), and a filter guaranteed to hit something (ie, "e"). Then, go to the console window and check the "Auto Start BitTorrent" box. Finally, go to the File Menu and click Update. If things are working correctly, the torrent should be downloaded and after a few moments, your Bit Torrent client will open and begin the download.
Once these details are all correct, you can start using Buttress!
First, a quick word on how Buttress works.
Periodically, Buttress checks the RSS feeds it has listed for new items (i.e. new items that have been released since the last time it updated). It then checks those new items against the filters entered by the user. If there is a match (i.e. if a word from a filter appears in the title of the new item), Buttress downloads the torrent and begins the client, passing it the torrent file to start the download.
Feeds (or RSS feeds to be more precise) are what Buttress uses to check what torrents appear on a website. If a torrent hosting website you use has an RSS feed, you can use Buttress to automatically download files that interest you.
Adding feeds for Buttress to check is simple. Simply right click in the Feeds box and select "Add Feed" or click on the "Items" menu and go to "Add Feed". A prompt will appear asking you to enter the URL of the feed you wish Buttress to check. Type (or paste) the URL in and then click OK. The new feed will appear in the left half of the main window.
It is important to make sure that you are linking to an RSS feed (otherwise nothing can be downloaded from the website that you give Buttress). RSS feeds are XML documents and usually look something like this. If you are unsure of whether a page is an RSS feed or not, post in our forum with a link and we'll help you out. It's not that hard anyway :)
Simply highlight the feed you want to edit/remove by clicking on it, then right click or go to the "Items" menu. Selecting "Edit Feed" will bring up a prompt where you can edit the feed URL. Selecting "Remove Feed" will delete the feed.
To view the actual feed itself, merely select it and right click it, and finally choose "Show Feed," then your default browser will open to the chosen RSS feed.
Filters are used to test if new items on RSS feeds should be downloaded. When Buttress connects to a feed, it checks whether any of the new items in that feed contain any of the filters. If they do, Buttress gets the torrent and begins the download.
To add a filter, right click in the Filters box and select "Add Filter" or go to the "Items" menu and click "Add Filter". A prompt will appear; enter a word that you want feeds checked for. For example, if we want Buttress to download anything with the word "foobar" in it, we'd enter foobar.
Click "OK". The filter will now appear in the right half of the main window.
Now, when Buttress finds new items on a feed, it will search for items with "foobar" in the title (or whatever word you actually typed) and if there are any matches, it will begin downloading them.
Buttress checks for matches in the title of an item in an RSS feed - this is the part that appears between the <title> </title> tags. The matching is case insensitive (i.e. FOO matches foo).
Currently, Buttress only supports filters of one word, though it does support regular expressions. Regular expression help can be found here.
Highlight the filter you wish to edit/remove by clicking on it. Then, right click and click "Edit Filter" or go to the "Items" menu and select "Edit Filter" if you wish to change a filter or Remove to delete it entirely.
Upon closing, Buttress will ask you if you wish to save the feeds and filters - if you click Yes, all will be saved; if you click No the feeds and filters you have added since last starting Buttress will be lost. You can also choose to save from the File menu, by clicking "Save Feeds."
If you wish to change your Bit Torrent client or you move your Buttress folder, update the paths in the config tab as described in the "Setting Up" section. Easy!
In the config tab is a field marked "Delay Between Updates." This is in minutes and is initially set to 10. This means that every 10 minutes, Buttress will connect to the RSS feeds and check for new items on the feeds.
If this is too often for your liking, simply enter a new number in the field and press the "Set Delay" button to the right of it. NOTE: This can not be set below 10 minutes.
By checking the "Auto Start BitTorrent" checkbox, Buttress will start your BitTorrent client automatically when it finds interesting feeds so that the files can be downloaded automatically. If the box is left unchecked, the torrents will be downloaded but the client not started... You'll have to start the torrents yourself later.
Just in case things go horribly wrong (and they might, programmers aren't perfect), you can help the situation by telling us about it. By turning on the "Email on Critical Error" option, whenever there's a critical error that isn't handled in some way, an email will be sent to us, the developers, telling us about the problem so that we can fix it.
Your privacy and anonymity are assured, as all emails sent to the developers appear to come from buttressapp@sailes.co.uk, which is not in fact your email (it's really the developers'). Note: It is suggested and requested that you turn this feature on, but not required for your enjoyment of Buttress in any way.
If you wish to force Buttress to check for new items, go to the File menu and select "Update". Buttress will connect to the RSS feeds and check any new items for instances of filter keywords.
What is the console for? It acts as a log for what Buttress is doing. It's helpful for debugging purposes but also for checking what has gone on while Buttress has been running. It may look difficult but it should be fairly self explanatory after playing around for a bit. Most users need not worry what it does.
When you hit the close button on Buttress, it does not actually quit the program. To do that, you'd need to use Ctrl+Q (or equivalent keys), or select "Quit" from the file menu. What it does do however, is minimize Buttress to the system tray. Minimize minimizes it to the taskbar (or equivalent on non-Windows systems), and close minimizes it to the system tray. From there, you can right click the icon to bring up options (restore, and quit, also "update" when 0.6 is released) or just left-click to restore the screen again.
In the not-quite-yet-publicly-released 0.6 (CVS) version of Buttress, we have a wonderful auto-update feature... When 0.6 is released (you can get this feature now in the CVS), it'll work like this... When a new release of Buttress is available, a dialog will pop up asking you if you want to update. If you do, Buttress will quit and you'll be taken to the Buttress Sourceforge site where you can download the new version. If you chose no, you'll be able to continue using Buttress like normal, but the box will keep popping up every time you start it up until you update...
Buttress is a program written in Java that uses user-entered filters to check RSS feeds for items that may be of interest to the user and begins downloading them if it finds any.
Q. What is Bit Torrent?Bit Torrent is a way of distributing files on a peer-to-peer basis. Basically, a user downloads a Torrent file which points toward a tracker; this tracker keeps track of who is downloading the file. Users swap information about who has what parts of the file being downloaded and download parts from eachother.
That's the gist of it anyway. For more information, visit the Official Introduction to Bit Torrent, or the Wikipedia entry for Bit Torrent.
Q. What is RSS?In essence, RSS is a method of providing information about articles that appear on a website. An illustration provides a better explanation.
Take the BBC news site as an example. People can visit the site in a browser to see the headlines as you'd expect. But they also run an RSS feed - this is an XML document that describes the top 10 or so stories on the site. An RSS Reader, retrieves this feed and displays the story summaries. If the user likes the sound of a story, they can click a link and be taken to the full story.
Buttress works in a similar way to an RSS Reader, except that it automatically retrieves torrent files based upon filters the user enters. Once the torrent is received, it is executed so the download begins.
Q. Does Buttress handle all RSS feeds (0.9, 0.91, 2.0)?Yes. If for some reason you find a feed that it doesn't work with, please, get in touch!
Q. Can I use regular expressions with Buttress?Yes indeed. Get help on regular expressions here.
Q. Can I use more than one 1 keyword for a filter?Erm, no, not yet but it might be a thing we'll work on for the next release.
Q. What is the CVS version?The CVS version is the very latest version - typically, the version that is being worked on for the next release. When we have finished putting a number of features into Buttress and we are happy they work correctly, we release a new version. We call these "releases" and recommend that most people use these.
The CVS version is the most up-to-date version, possibly with new features and/or functionality but these new features may not be fully working yet. When they are, typically a release is issued.
As just mentioned, we recommend the latest release for most users (i.e. NOT the CVS version) but feel free to give the CVS version a go, just do so at your own risk! :)
Q. When is the next version due? What extra will it do?Can't say. The extras in the next version aren't determined yet, and there's no release schedule prepared right now. Just check the Sourceforge site on occasion for updates...
Q. I've found something wrong! What should I do?First, make sure you've entered your paths correctly and that the addresses for your feeds are correct and working. If you still encounter problems, either leave a post in our forum or get in touch here.
Q. Can I help?If you think you can help with the development of Buttress, we'd like to hear from you! Drop us a line here and let us know how you think you could help. Please get in touch before you start coding!
Q. I have an idea!Great! Drop us a line here or here and we'll get back to you!
Q. My question isn't answered here! :(Send us any questions you have, and we'll get back to you (and maybe even include it here!).
Last updated: 04-10-30 : 12:50 PM EST
Authors:
Revision 3 (0.5.1 + CVS) - Nick Daly
Revision 2 (0.5) - Nick Daly
Revision 1 (0.32) - Gary Breavington