1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|
BUILDING rdiscount
==================
You'll be needing Ruby, rake, and a basic build environment.
Build the rdiscount extension for tests and local development:
$ rake build
Use your rdiscount working copy when running ruby programs:
$ export RUBYLIB=~/rdiscount/lib:$RUBYLIB
$ ruby some-program.rb
Gathering changes from an upstream discount clone requires first
grabbing the discount submodule into the root of the project and then running
the rake gather task to copy discount source files into the ext/ directory:
$ git submodule update --init
Submodule 'discount' (git@github.com:Orc/discount.git) registered for path 'discount'
Cloning into discount...
$ cd discount
$ ./configure.sh
$ make # ensure it compiles
$ cd ..
$ rake gather
$ rake build
UPGRADING Discount
==================
The most common maintenance task is upgrading the version of Discount that
RDiscount is using.
Before doing anything, make sure you can build the current (unmodified) version
of RDiscount. See the section above for details.
Update the Discount submodule to the desired version:
$ cd discount
$ git fetch
$ git checkout v2.0.7.x # insert desired version
$ cd ..
Copy the new Discount sources to the appropriate directories for RDiscount:
$ rake gather
Update rdiscount.gemspec to include all *.c, *.h, and *.rb files in ext:
$ rake rdiscount.gemspec
Build the RDiscount gem. If you get errors related to missing files
in ext, make sure you updated the gemspec correctly in the previous step.
$ gem build rdiscount.gemspec
Install this new gem locally. It is recommended that you use RVM to
create an isolated installation environment. If you get an error after the line
"Building native extensions", see the troubleshooting section below.
$ rvm ruby@rdiscount --create # recommended; requires RVM
$ gem install rdiscount-*.gem
Make sure the gem can be imported:
$ ruby -e 'require "rdiscount"'
Make sure the tests (still) pass:
$ rake test
Worked? Swell! The hard part is past.
Check the Discount release notes to determine whether it has gained any new
features that should be exposed through the RDiscount Ruby interface
(lib/rdiscount.rb), such as new MKD_* flags or configure flags.
If so, update the Ruby interface.
If the ./configure.sh line needs to be changed to support new features,
you will need to port some #defines from discount/config.h to ext/config.h
manually to get RDiscount's embedded Discount to use the same configure flags.
For new Discount extensions via new MKD_* flags, you will need to update:
* lib/rdiscount.rb with new accessors and
* the rb_rdiscount__get_flags function in ext/rdiscount.c with new
accessor-to-flag mappings for each new extension.
You should also look for RDiscount-specific bugs & feature requests in the
GitHub tracker and fix a few.
If any bugs were fixed or features added be sure to also add new tests!
And don't forget to rerun the preexisting tests.
Update the CHANGELOG.
Update rdiscount.gemspec with the new RDiscount version number.
Also update the VERSION constant in lib/rdiscount.rb.
Push that change as the final commit with a message in the format
"2.0.7 release".
Tag the release commit:
$ git tag 2.0.7 # insert desired version
Rebuild the gem file and push it to RubyGems.
$ gem build rdiscount.gemspec
$ gem push rdiscount-NEW_VERSION.gem
Announce the new release! For releases with new features it is recommended to
write a full blog post.
Troubleshooting Native Extension Issues
---------------------------------------
The most likely place where errors will crop up is when you attempt to build
the C extension. If this happens, you will have to debug manually. Below are
a few recommended sanity checks:
Ensure the Makefile is generated correctly:
$ cd ext
$ ruby extconf.rb
Ensure make succeeds:
$ make
If you get linker errors related to there being duplicate symbols for _main,
you probably need to update the deploy target of the Rakefile to exclude
new *.c files from Discount that have a main function.
For issues related to config.h or extconf.rb, there was probably some
change to Discount's configure.sh that broke them. You will probably need
to update these files in ext/ manually.
For other errors, you'll have to investigate yourself. Common error classes:
* 'ext/configure.sh' fails:
- Create a patch to the upstream Discount.
* Some files missing from ext/ that are present in discount/:
- Update 'rake deploy' target to copy more files.
* Some files missing when `gem build` is run:
- Update gemspec to enumerate the correct files in ext/.
|
