Awful is an iOS 15.0+ app that's Better Than Safari for browsing the Something Awful Forums. Its story is told in its thread (and the thread before that (and the thread before that (and the thread before that))).
Not sure what to work on? There's a list of issues, or just post in the thread and someone will share their pet peeves for your amusement!
This app is not endorsed by Something Awful.
Please drop by the thread if you could use a hand with any of these steps!
You need Xcode 15 to build and run Awful. You can download Xcode for free from Apple. Then:
- Clone the repository:
git clone --recursive https://github.com/Awful/Awful.app Awful-app - Open the Xcode project and build away:
xed Awful-app
You may see build warnings of the form "Unable to find included file '../Local.xcconfig'". You should still be able to build and run, just with a couple of features turned off. If you'd like to enable those features, or just make the warnings go away, please scroll on down to the "Local build settings" section below.
The only required dependencies for building Awful that are not included directly in this repository are those managed by Swift Package Manager. Files generated by other utilities are included in the repository. The only submodule is the thread-tags repository, which is not strictly needed for building; if you don't need it, you can leave off the --recursive part from step one.
If you'd like to build to your device, set the DEVELOPMENT_TEAM build setting as mentioned in the Local build settings section below.
There are some local build settings that can be useful to include but should not be committed to a public repo. Store those in an Xcode configuration file at Local.xcconfig; see Local.sample.xcconfig for an example. You'll get a build warning until you put a file at that location; it can be an empty file if you just want Xcode to be quiet.
Awful uses an App Group to communicate and share data with the Smilie Keyboard. Unfortunately, App Group identifiers must be unique, so we can't simply set it up in this repository and have it work for everybody work. By default, Awful builds without an App Group configured, which means that the Smilie Keyboard won't be able to download new smilies, remember recent smilies, or store favourite smilies. If you like, you can:
- Create an App Group in your iOS Developer account.
- Copy
Local.sample.entitlementstoLocal.entitlements. - Copy and paste your App Group identifier into
Local.entitlements. - Set the
CODE_SIGN_ENTITLEMENTSbuild setting inLocal.xcconfigfor the targetsAwfulandSmilieKeyboard(seeLocal.sample.xcconfigfor a suggested setup). - After a build and run, full keyboard functionality should be yours.
There are unit tests, that don't cover much, running continuously via GitHub Actions.
Dependencies not managed via Swift Package Manager are placed in the Vendor folder and manually kept up-to-date. They include:
- ARChromeActivity and TUSafariActivity assets. We've implemented our own
UIActivitysubclasses but continue to use the libraries' images. - MRProgress, PSMenuItem, and PullToRefresh, which do not have their own
Package.swift. (If you know otherwise, let's move it over!)
Bump the major version when changing the minimum required iOS version (deployment target). Otherwise, bump the minor version.
Also, when changing the iOS deployment target, please tag the last commit that supports any no-longer-supported deployment target(s) and update the table in the section "iOS deployment targets" below.
If you peek in the Scripts folder you'll find:
beta, a script that bumps the build number and then runsxcodebuildto create an archive suitable for uploading to App Store Connect. Seebeta --helpfor more, including how to set up automatic uploads to App Store Connect.- If you've released to the App Store, it's time to bump at least the minor version number by passing the
--minorparameter, e.g.beta --minor.
- If you've released to the App Store, it's time to bump at least the minor version number by passing the
bump, a script that can increment the build, minor, or major version number throughtout the project. Seebump --helpfor more.
And in the Xcode project itself you'll find:
SmilieExtractor, an iOS app that takesshowsmilies.webarchiveand extracts resources for Smilie Keyboard. To update smilies, first save a freshshowsmilies.webarchivefrom the Forums, then runSmilieExtractor.CopyMarkdownApp, a macOS Safari App Extension that adds a "Copy Awful Markdown" context menu item to the Forums. The copied markdown is ready to be pasted into a GitHub issue.
If you've stashed some .html files from the Forums, you can load those into a debug build of the app. And if you forgot to stash some, you're in luck: we've stashed some as test fixtures. See FixtureURLProtocol for more info.
You can help! See our contribution guidelines and please come visit the thread to say hi.
Awful is broken down somewhat:
Awfulis the iOS app.AwfulCoreis a Swift package that does the scraping and networking with the Forums. It's meant to be compatible with all Apple platforms, but nobody's really tried beyond iOS.Smiliesis a Swift package that downloads smilies and presents them as a keyboard. It's meant to be compatible with all Apple platforms, but nobody's really tried beyond iOS.
Awful's posts view is fully customizable using CSS. There's a default theme, as well as themes for specific forums such as YOSPOS and FYAD. We use Less to generate our stylesheets during Awful's build process, so you'll want to edit .less files but you'll see .css files in the build products and in the Web Inspector.
The rest of Awful is themed in a a big plist. If you can't find a theme key you'd like to use, ask and we'll add it!
Diabolik900 and The Dave have largely fashioned Awful with its own [set of thread tags][thread tags] that look great on the iPhone and the iPad. They're distributed with the app. New thread tags can also appear in Awful without us having to send an update through the App Store. This is done by hosting the icons via GitHub Pages.
To add a new thread tag you just made:
-
Add it to the thread tags repository and push.
-
Update the awfulapp.com repository repository per its README.
-
In this (Awful.app) repository, update the
App/Resources/Thread Tagssubmodule and push:cd path/to/awful-app/repo cd App/Resources/Thread\ Tags git pull origin master cd .. git commit -am "Updated thread tags." git push
To add a new alternative app icon:
- Open
App/App Icons.xcassets. - Add a new iOS App Icon.
- Name your app icon something appropriate, including the
_appiconsuffix. - Drag your 1024×1024 image file over.
- Add a new Image Set with the same name as your icon set plus
_preview. - Drag 60pt icons into your preview icon set.
- Open
App/Settings/SettingsViewController.swift. - Add your new app icon info to the
appIconsarray.
The bookkeeping and duplicate images are unfortunate, but there's no public API to list app icon sets or to load app icon images for display. Instead of hacking together something that could break later, we'll do it ourselves.
Awful answers to a couple URL schemes:
awful:opens Awful directly to various screens. This URL scheme is documented at http://handleopenurl.com and at Launch Center Pro.awful://forumsopens the Forums tab.awful://forums/:forumidopens the Forums tab to the identified forum.awful://threads/:threadidopens the first page of the identified thread. For example,awful://threads/3510131opens Awful's thread.awful://threads/:threadid/pages/:pageopens the given page of the identified thread. For example,awful://threads/3510131/pages/15opens the fifteenth page of Awful's thread.awful://posts/:postidopens the identified post's page of its thread and jumps to it. For example,awful://posts/408179339opens the OP of Awful's thread.awful://bookmarksopens the Bookmarks tab.awful://messagesopens the Messages tab.awful://messages/:messageidopens the identified private message. (I guess the idea is to handle a link from one message to another?)awful://settingsopens the Settings tab.awful://users/:useridopens the identified user's profile. For example,awful://users/106125opens pokeyman's profile.awful://banlistopens the Leper's Colony.awful://banlist/:useridopens the identified user's rap sheet. For example,awful://banlist/106125opens pokeyman's rap sheet.
awfulhttp:andawfulhttps:handle Forums website URLs by opening the corresponding screen when possible.- The idea is you take your
https://forums.somethingawful.com/…URL, putawfulin front, and now it opens in Awful.
- The idea is you take your
| For iOS | Check out tag/branch |
|---|---|
| 17 | main |
| 16 | main |
| 15 | main |
| 14 | ios-14 |
| 13 | ios-13 |
| 12 | ios-12 |
| 11 | ios-11 |
| 10 | ios-10 |
| 9 | ios-9 |
| 8 | ios-8 |
| 7 | ios-7 |
| 6 | ios-6 |
| 5 | ios-5 |
Creative Commons Attribution-NonCommercial-ShareAlike 3.0 United States License
Awful development is led by pokeyman aka Nolan Waite.
Awful includes contributions from:
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent